ncurses 6.1 - patch 20180519
[ncurses.git] / man / terminfo.head
index 7455675ab953cd7d661320e62ec65c74a828b97a..24d4e2a5621a0ad43febd4375f7384bb0a4d4cad 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2004,2006 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: terminfo.head,v 1.16 2007/03/04 00:09:46 tom Exp $
+.\" $Id: terminfo.head,v 1.33 2018/05/19 20:57:27 tom Exp $
 .TH terminfo 5 "" "" "File Formats"
 .ds n 5
 .ds d @TERMINFO@
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.de NS
+.ie n  .sp
+.el    .sp .5
+.ie n  .in +4
+.el    .in +2
+.nf
+.ft C                  \" Courier
+..
+.de NE
+.fi
+.ft R
+.in -4
+..
 .SH NAME
 terminfo \- terminal capability data base
 .SH SYNOPSIS
@@ -47,38 +68,62 @@ have, by specifying how to perform screen operations, and by
 specifying padding requirements and initialization sequences.
 This describes \fBncurses\fR
 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+.SS Terminfo Entry Syntax
 .PP
 Entries in
 .I terminfo
-consist of a sequence of `,' separated fields (embedded commas may be
-escaped with a backslash or notated as \\054).
-White space after the `,' separator is ignored.
-The first entry for each terminal gives the names which are known for the
-terminal, separated by `|' characters.
-The first name given is the most common abbreviation for the terminal,
-the last name given should be a long name fully identifying the terminal,
-and all others are understood as synonyms for the terminal name.
-All names but the last should be in lower case and contain no blanks;
+consist of a sequence of fields:
+.bP
+Each field ends with a comma \*(``,\*('' 
+(embedded commas may be
+escaped with a backslash or written as \*(``\\054\*('').
+.bP
+White space between fields is ignored.
+.bP
+The first field in a \fIterminfo\fP entry begins in the first column.
+.bP
+Newlines and leading whitespace (spaces or tabs)
+may be used for formatting entries for readability.
+These are removed from parsed entries.
+.IP
+The \fB@INFOCMP@\fP \fB\-f\fP and \fB\-W\fP options rely on this to
+format if-then-else expressions,
+or to enforce maximum line-width.
+The resulting formatted terminal description can be read by \fB@TIC@\fP.
+.bP
+The first field for each terminal gives the names which are known for the
+terminal, separated by \*(``|\*('' characters.
+.IP
+The first name given is the most common abbreviation for the terminal
+(its primary name),
+the last name given should be a long name fully identifying the terminal
+(see \fBlongname\fP(3X)),
+and all others are treated as synonyms (aliases) for the primary terminal name.
+.IP
+X/Open Curses advises that all names but the last should be in lower case
+and contain no blanks;
 the last name may well contain upper case and blanks for readability.
-.PP
-Lines beginning with a `#' in the first column are treated as comments.
+.IP
+This implementation is not so strict;
+it allows mixed case in the primary name and aliases.
+If the last name has no embedded blanks,
+it allows that to be both an alias and a verbose name
+(but will warn about this ambiguity).
+.bP
+Lines beginning with a \*(``#\*('' in the first column are treated as comments.
+.IP
 While comment lines are legal at any point, the output of \fB@CAPTOINFO@\fP
 and \fB@INFOTOCAP@\fP (aliases for \fB@TIC@\fP)
 will move comments so they occur only between entries.
 .PP
-Newlines and leading tabs may be used for formatting entries for readability.
-These are removed from parsed entries.
-The \fB@INFOCMP@\ -f\fP option relies on this to format if-then-else expressions:
-the result can be read by \fB@TIC@\fP.
-.PP
 Terminal names (except for the last, verbose entry) should
 be chosen using the following conventions.
 The particular piece of hardware making up the terminal should
-have a root name, thus ``hp2621''.
+have a root name, thus \*(``hp2621\*(''.
 This name should not contain hyphens.
 Modes that the hardware can be in, or user preferences, should
 be indicated by appending a hyphen and a mode suffix.
-Thus, a vt100 in 132 column mode would be vt100-w.
+Thus, a vt100 in 132 column mode would be vt100\-w.
 The following suffixes should be used where possible:
 .PP
 .TS
@@ -86,22 +131,88 @@ center ;
 l c l
 l l l.
 \fBSuffix      Meaning Example\fP
--\fInn\fP      Number of lines on the screen   aaa-60
--\fIn\fPp      Number of pages of memory       c100-4p
--am    With automargins (usually the default)  vt100-am
--m     Mono mode; suppress color               ansi-m
--mc    Magic cookie; spaces when highlighting  wy30-mc
--na    No arrow keys (leave them in local)     c100-na
--nam   Without automatic margins               vt100-nam
--nl    No status line                          att4415-nl
--ns    No status line                          hp2626-ns
--rv    Reverse video                           c100-rv
--s     Enable status line                      vt100-s
--vb    Use visible bell instead of beep        wy370-vb
--w     Wide mode (> 80 columns, usually 132)   vt100-w
+\-\fInn\fP     Number of lines on the screen   aaa\-60
+\-\fIn\fPp     Number of pages of memory       c100\-4p
+\-am   With automargins (usually the default)  vt100\-am
+\-m    Mono mode; suppress color               ansi\-m
+\-mc   Magic cookie; spaces when highlighting  wy30\-mc
+\-na   No arrow keys (leave them in local)     c100\-na
+\-nam  Without automatic margins               vt100\-nam
+\-nl   No status line                          att4415\-nl
+\-ns   No status line                          hp2626\-ns
+\-rv   Reverse video                           c100\-rv
+\-s    Enable status line                      vt100\-s
+\-vb   Use visible bell instead of beep        wy370\-vb
+\-w    Wide mode (> 80 columns, usually 132)   vt100\-w
 .TE
 .PP
-For more on terminal naming conventions, see the \fBterm(7)\fR manual page.
-.SS Capabilities
+For more on terminal naming conventions, see the \fBterm\fP(7) manual page.
+.SS Terminfo Capabilities Syntax
+.PP
+The terminfo entry consists of several \fIcapabilities\fP,
+i.e., features that the terminal has,
+or methods for exercising the terminal's features.
+.PP
+After the first field (giving the name(s) of the terminal entry),
+there should be one or more \fIcapability\fP fields.
+These are boolean, numeric or string names with corresponding values:
+.bP
+Boolean capabilities are true when present, false when absent.
+There is no explicit value for boolean capabilities.
+.bP
+Numeric capabilities have a \*(``#\*('' following the name,
+then an unsigned decimal integer value.
+.bP
+String capabilities have a \*(``=\*('' following the name,
+then an string of characters making up the capability value.
+.IP
+String capabilities can be split into multiple lines,
+just as the fields comprising a terminal entry can be
+split into multiple lines.
+While blanks between fields are ignored,
+blanks embedded within a string value are retained,
+except for leading blanks on a line.
+.PP
+Any capability can be \fIcanceled\fP,
+i.e., suppressed from the terminal entry,
+by following its name with \*(``@\*(''
+rather than a capability value.
+.SS Similar Terminals
+.PP
+If there are two very similar terminals, one (the variant) can be defined as
+being just like the other (the base) with certain exceptions.
+In the
+definition of the variant, the string capability \fBuse\fR can be given with
+the name of the base terminal:
+.bP
+The capabilities given before
+.B use
+override those in the base type named by
+.BR use .
+.bP
+If there are multiple \fBuse\fR capabilities, they are merged in reverse order.
+That is, the rightmost \fBuse\fR reference is processed first, then the one to
+its left, and so forth.
+.bP
+Capabilities given explicitly in the entry override
+those brought in by \fBuse\fR references.
+.PP
+A capability can be canceled by placing \fBxx@\fR to the left of the
+use reference that imports it, where \fIxx\fP is the capability.
+For example, the entry
+.RS
+.PP
+2621\-nl, smkx@, rmkx@, use=2621,
+.RE
+.PP
+defines a 2621\-nl that does not have the \fBsmkx\fR or \fBrmkx\fR capabilities,
+and hence does not turn on the function key labels when in visual mode.
+This is useful for different modes for a terminal, or for different
+user preferences.
+.PP
+An entry included via \fBuse\fP can contain canceled capabilities,
+which have the same effect as if those cancels were inline in the
+using terminal entry.
+.SS Predefined Capabilities
 .\" Head of terminfo man page ends here
 .ps -1