X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fterminfo.head;h=f6a31c8055dc679e93262e241f0140f37ec9e04c;hp=fcd27e3ab4f5dd30cfee2345d411be28c6f643f4;hb=152c5a605234b7ea36ba3a03ec07e124bb6aac75;hpb=ce4803687b821efbc5fb2c5a5f06d69cd4dc2656;ds=sidebyside

diff --git a/man/terminfo.head b/man/terminfo.head
index fcd27e3a..f6a31c80 100644
--- a/man/terminfo.head
+++ b/man/terminfo.head
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: terminfo.head,v 1.23 2017/02/18 17:04:53 tom Exp $
+.\" $Id: terminfo.head,v 1.39 2020/02/02 23:34:34 tom Exp $
 .TH terminfo 5 "" "" "File Formats"
 .ds n 5
 .ds d @TERMINFO@
@@ -35,7 +36,22 @@
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
 .de bP
-.IP \(bu 4
+.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
+.ie n  .in -4
+.el    .in -2
 ..
 .SH NAME
 terminfo \- terminal capability data base
@@ -43,41 +59,72 @@ terminfo \- terminal capability data base
 \*d/*/*
 .SH DESCRIPTION
 .I Terminfo
-is a data base describing terminals, used by screen-oriented programs such as
+is a data base describing terminals,
+used by screen-oriented programs such as
 \fBnvi\fR(1),
-\fBrogue\fR(1)
-and libraries such as
-\fBcurses\fR(3X).
+\fBlynx\fR(1),
+\fBmutt\fR(1),
+and other curses applications,
+using high-level calls to libraries such as \fBcurses\fR(3X).
+It is also used via low-level calls by non-curses applications
+which may be screen-oriented (such as \fB@CLEAR@\fP(1))
+or non-screen (such as \fB@TABS@\fP(1)).
+.PP
 .I Terminfo
 describes terminals by giving a set of capabilities which they
 have, by specifying how to perform screen operations, and by
 specifying padding requirements and initialization sequences.
-This describes \fBncurses\fR
+.PP
+This manual 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
+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.
-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;
+.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
+.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
@@ -85,7 +132,7 @@ 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
@@ -108,7 +155,73 @@ l l l.
 \-w	Wide mode (> 80 columns, usually 132)	vt100\-w
 .TE
 .PP
-For more on terminal naming conventions, see the \fBterm(7)\fR manual page.
+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