Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 464 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man5/user_caps.5 b/upstream/mageia-cauldron/man5/user_caps.5
new file mode 100644
index 00000000..ad809362
--- /dev/null
+++ b/upstream/mageia-cauldron/man5/user_caps.5
@@ -0,0 +1,464 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 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            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: user_caps.5,v 1.47 2024/01/13 22:05:39 tom Exp $
+.TH user_caps 5 2024-01-13 "ncurses 6.4" "File formats"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.SH NAME
+user_caps \-
+user-defined \fIterminfo\fR capability format
+.SH SYNOPSIS
+.B infocmp \-x
+.PP
+.B tic \-x
+.SH DESCRIPTION
+.SS Background
+Before \fI\%ncurses\fP 5.0,
+terminfo databases used a \fIfixed repertoire\fP of terminal
+capabilities designed for the SVr2 terminal database in 1984,
+and extended in stages through SVr4 (1989),
+and standardized in the Single Unix Specification beginning in 1995.
+.PP
+Most of the \fIextensions\fP in this fixed repertoire were additions
+to the tables of Boolean, numeric and string capabilities.
+Rather than change the meaning of an existing capability, a new name was added.
+The terminfo database uses a binary format; binary compatibility was
+ensured by using a header which gave the number of items in the
+tables for each type of capability.
+The standardization was incomplete:
+.bP
+The \fIbinary format\fP itself is not described
+in the X/Open Curses documentation.
+Only the \fIsource format\fP is described.
+.IP
+Library developers rely upon the SVr4 documentation,
+and reverse-engineering the compiled terminfo files to match the binary format.
+.bP
+Lacking a standard for the binary format, most implementations
+copy the SVr2 binary format, which uses 16-bit signed integers,
+and is limited to 4096-byte entries.
+.IP
+The format cannot represent very large numeric capabilities,
+nor can it represent large numbers of special keyboard definitions.
+.bP
+The tables of capability names differ between implementations.
+.IP
+Although they \fImay\fP provide all of the standard capability names,
+the position in the tables differs because some features were added as needed,
+while others were added (out of order) to comply with X/Open Curses.
+.IP
+While \fI\%ncurses\fP' repertoire of predefined capabilities is closest
+to Solaris,
+Solaris's terminfo database has a few differences from
+the list published by X/Open Curses.
+For example,
+\fI\%ncurses\fP can be configured with tables which match the terminal
+databases for AIX, HP-UX or OSF/1,
+rather than the default Solaris-like configuration.
+.bP
+In SVr4 curses and \fI\%ncurses\fP,
+the terminal database is defined at compile-time using a text file
+which lists the different terminal capabilities.
+.IP
+In principle, the text-file can be extended,
+but doing this requires recompiling and reinstalling the library.
+The text-file used in \fI\%ncurses\fP for terminal capabilities includes
+details for various systems past the documented X/Open Curses features.
+For example, \fI\%ncurses\fP supports these capabilities in each configuration:
+.RS 8
+.TP 5
+memory_lock
+(meml)
+lock memory above cursor
+.TP 5
+memory_unlock
+(memu)
+unlock memory
+.TP 5
+box_chars_1
+(box1)
+box characters primary set
+.RE
+.IP
+The memory lock/unlock capabilities were included because they were used
+in the X11R6 terminal description for \fBxterm\fP(1).
+The \fIbox1\fP capability is used in tic to help with terminal descriptions
+written for AIX.
+.PP
+During the 1990s, some users were reluctant to use terminfo
+in spite of its performance advantages over termcap:
+.bP
+The fixed repertoire prevented users from adding features
+for unanticipated terminal improvements
+(or required them to reuse existing capabilities as a workaround).
+.bP
+The limitation to 16-bit signed integers was also mentioned.
+Because termcap stores everything as a string,
+it could represent larger numbers.
+.PP
+Although termcap's extensibility was rarely used
+(it was never the \fIspeaker\fP who had actually used the feature),
+the criticism had a point.
+\fI\%ncurses\fP 5.0 provided a way to detect nonstandard capabilities,
+determine their
+type and optionally store and retrieve them in a way which did not interfere
+with other applications.
+These are referred to as \fIuser-defined capabilities\fP because no
+modifications to the toolset's predefined capability names are needed.
+.PP
+The \fI\%ncurses\fP utilities \fBtic\fP and \fBinfocmp\fP have a
+command-line option \*(``\-x\*('' to control whether the nonstandard
+capabilities are stored or retrieved.
+A library function \fBuse_extended_names\fP
+is provided for the same purpose.
+.PP
+When compiling a terminal database, if \*(``\-x\*('' is set,
+\fBtic\fP will store a user-defined capability if the capability name is not
+one of the predefined names.
+.PP
+Because \fI\%ncurses\fP provides a termcap library interface,
+these user-defined capabilities may be visible to termcap applications:
+.bP
+The termcap interface (like all implementations of termcap)
+requires that the capability names are 2-characters.
+.IP
+When the capability is simple enough for use in a termcap application,
+it is provided as a 2-character name.
+.bP
+There are other
+user-defined capabilities which refer to features not usable in termcap,
+e.g., parameterized strings that use more than two parameters
+or use more than the trivial expression support provided by termcap.
+For these, the terminfo database should have only capability names with
+3 or more characters.
+.bP
+Some terminals can send distinct strings for special keys (cursor-,
+keypad- or function-keys) depending on modifier keys (shift, control, etc.).
+While terminfo and termcap have a set of 60 predefined function-key names,
+to which a series of keys can be assigned,
+that is insufficient for more than a dozen keys multiplied by more than
+a couple of modifier combinations.
+The \fI\%ncurses\fP database uses a convention based on \fBxterm\fP(1)
+to provide extended special-key names.
+.IP
+Fitting that into termcap's limitation of 2-character names
+would be pointless.
+These extended keys are available only with terminfo.
+.SS "Recognized Capabilities"
+The \fI\%ncurses\fP library uses the user-definable capabilities.
+While the terminfo database may have other extensions,
+\fI\%ncurses\fP makes explicit checks for these:
+.RS 3
+.TP 3
+AX
+\fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
+by resetting the foreground and background color, respectively, to the default.
+.IP
+This is a feature recognized by the \fBscreen\fP program as well.
+.TP 3
+E3
+\fIstring\fP, tells how to clear the terminal's scrollback buffer.
+When present, the \fBclear\fP(1) program sends this before clearing
+the terminal.
+.IP
+The command \*(``\fBtput clear\fP\*('' does the same thing.
+.TP 3
+NQ
+\fIBoolean\fP,
+used to suppress a consistency check in tic for the \fI\%ncurses\fP
+capabilities
+in user6 through user9 (u6, u7, u8 and u9)
+which tell how to query the terminal's cursor position
+and its device attributes.
+.TP 3
+RGB
+\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
+used to assert that the
+\fBset_a_foreground\fP and
+\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
+using an RGB (red/green/blue) convention.
+This capability allows the \fBcolor_content\fP function to
+return appropriate values without requiring the application
+to initialize colors using \fBinit_color\fP.
+.IP
+The capability type determines the values which \fI\%ncurses\fP sees:
+.RS 3
+.TP 3
+\fIBoolean\fP
+implies that the number of bits for red, green and blue are the same.
+Using the maximum number of colors,
+\fI\%ncurses\fP adds two,
+divides that sum by three,
+and assigns the result to red,
+green and blue in that order.
+.IP
+If the number of bits needed for the number of colors is not a multiple
+of three, the blue (and green) components lose in comparison to red.
+.TP 3
+\fInumber\fP
+tells \fI\%ncurses\fP what result to add to red, green and blue.
+If \fI\%ncurses\fP runs out of bits,
+blue (and green) lose just as in the \fIBoolean\fP case.
+.TP 3
+\fIstring\fP
+explicitly list the number of bits used for red, green and blue components
+as a slash-separated list of decimal integers.
+.RE
+.IP
+Because there are several RGB encodings in use,
+applications which make assumptions about the number of bits per color
+are unlikely to work reliably.
+As a trivial case, for example, one could define \fBRGB#1\fP
+to represent the standard eight ANSI colors, i.e., one bit per color.
+.TP 3
+U8
+\fInumber\fP,
+asserts that \fI\%ncurses\fP must use Unicode values for line-drawing
+characters,
+and that it should ignore the alternate character set capabilities
+when the locale uses UTF-8 encoding.
+For more information, see the discussion of
+\fBNCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3X).
+.IP
+Set this capability to a nonzero value to enable it.
+.TP 3
+XM
+\fIstring\fP,
+override \fI\%ncurses\fP's built-in string which
+enables/disables \fBxterm\fP(1) mouse mode.
+.IP
+\fI\%ncurses\fP sends a character sequence to the terminal to initialize mouse mode,
+and when the user clicks the mouse buttons or (in certain modes) moves the
+mouse, handles the characters sent back by the terminal to tell it what
+was done with the mouse.
+.IP
+The mouse protocol is enabled when
+the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
+By default,
+\fI\%ncurses\fP handles the responses for the X11 xterm mouse protocol.
+It also knows about the \fISGR 1006\fP xterm mouse protocol,
+but must to be told to look for this specifically.
+It will not be able to guess which mode is used,
+because the responses are enough alike that only confusion would result.
+.IP
+The \fBXM\fP capability has a single parameter.
+If nonzero, the mouse protocol should be enabled.
+If zero, the mouse protocol should be disabled.
+\fI\%ncurses\fP inspects this capability if it is present,
+to see whether the 1006 protocol is used.
+If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
+.IP
+The xterm mouse protocol is used by other terminal emulators.
+The terminal database uses building-blocks for the various xterm mouse
+protocols which can be used in customized terminal descriptions.
+.IP
+The terminal database building blocks for this mouse
+feature also have an experimental capability \fIxm\fP.
+The \*(``xm\*('' capability describes the mouse response.
+Currently there is no interpreter which would use this
+information to make the mouse support completely data-driven.
+.IP
+\fIxm\fP shows the format of the mouse responses.
+In this experimental capability, the parameters are
+.RS 5
+.TP 5
+.I p1
+y-ordinate
+.TP 5
+.I p2
+x-ordinate
+.TP 5
+.I p3
+button
+.TP 5
+.I p4
+state, e.g., pressed or released
+.TP 5
+.I p5
+y-ordinate starting region
+.TP 5
+.I p6
+x-ordinate starting region
+.TP 5
+.I p7
+y-ordinate ending region
+.TP 5
+.I p8
+x-ordinate ending region
+.RE
+.IP
+Here are examples from the terminal database for the most commonly used
+xterm mouse protocols:
+.IP
+.nf
+  xterm+x11mouse|X11 xterm mouse protocol,
+          kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;,
+          xm=\eE[M
+             %?%p4%t%p3%e%{3}%;%'\ '%+%c
+             %p2%'!'%+%c
+             %p1%'!'%+%c,
+
+  xterm+sm+1006|xterm SGR-mouse,
+          kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;,
+          xm=\eE[<%i%p3%d;
+             %p1%d;
+             %p2%d;
+             %?%p4%tM%em%;,
+.fi
+.
+.SS "Extended Key Definitions"
+Several terminals provide the ability to send distinct strings for
+combinations of modified special keys.
+There is no standard for what those keys can send.
+.PP
+Since 1999, \fBxterm\fP(1) has supported
+\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
+distinct special-key strings.
+In a terminal description,
+\fI\%ncurses\fP has no special knowledge of the modifiers used.
+Applications can use the \fInaming convention\fP established for \fBxterm\fP
+to find these special keys in the terminal description.
+.PP
+Starting with the
+.I curses
+convention that capability codes describing the input generated by a
+terminal's key caps begin with \*(``k\*('',
+and that shifted special keys use uppercase letters in their names,
+.IR \%ncurses 's
+terminal database defines the following names and codes to which a
+suffix is added.
+.PP
+.RS 5
+.TS
+Lb Lb
+Lb Lx.
+Code	Description
+_
+kDC	shifted kdch1 (delete character)
+.\" kDC is a standard capability; see X/Open Curses Issue 7, p. 345.
+kDN	shifted kcud1 (cursor down)
+kEND	shifted kend (end)
+kHOM	shifted khome (home)
+kLFT	shifted kcub1 (cursor back)
+kNXT	shifted knext (next)
+kPRV	shifted kprev (previous)
+kRIT	shifted kcuf1 (cursor forward)
+kUP	shifted kcuu1 (cursor up)
+.TE
+.RE
+.PP
+Keycap nomenclature on the Unix systems for which
+.I curses
+was developed differs from today's ubiquitous descendants of the IBM
+PC/AT keyboard layout.
+In the foregoing,
+interpret \*(``backward\*('' as \*(``left\*('',
+\*(``forward\*('' as \*(``right\*('',
+\*(``next\*('' as \*(``page down\*('',
+and
+\*(``prev(ious)\*('' as \*(``page up\*(''.
+.PP
+These are the suffixes used to denote the modifiers:
+.PP
+.RS 5
+.TS
+tab(/) ;
+l l .
+\fBValue\fP/\fBDescription\fP
+_
+2/Shift
+3/Alt
+4/Shift + Alt
+5/Control
+6/Shift + Control
+7/Alt + Control
+8/Shift + Alt + Control
+9/Meta
+10/Meta + Shift
+11/Meta + Alt
+12/Meta + Alt + Shift
+13/Meta + Ctrl
+14/Meta + Ctrl + Shift
+15/Meta + Ctrl + Alt
+16/Meta + Ctrl + Alt + Shift
+.TE
+.RE
+.PP
+None of these are predefined; terminal descriptions can refer to \fInames\fP
+which \fI\%ncurses\fP will allocate at runtime to \fIkey-codes\fP.
+To use these keys in an \fI\%ncurses\fP program,
+an application could do this:
+.bP
+using a list of extended key \fInames\fP,
+ask \fBtigetstr\fP(3X) for their values, and
+.bP
+given the list of values,
+ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
+would be returned for those keys by \fBwgetch\fP(3X).
+.\"
+.SH PORTABILITY
+The \*(``\-x\*('' extension feature of \fBtic\fP and \fBinfocmp\fP
+has been adopted in NetBSD curses.
+That implementation stores user-defined capabilities,
+but makes no use of these capabilities itself.
+.\"
+.SH AUTHORS
+Thomas E. Dickey
+.br
+beginning with \fI\%ncurses\fP 5.0 (1999)
+.\"
+.SH SEE ALSO
+\fB\%infocmp\fP(1M),
+\fB\%tic\fP(1M)
+.PP
+The terminal database section
+.I "NCURSES USER-DEFINABLE CAPABILITIES"
+summarizes commonly-used user-defined capabilities
+which are used in the terminal descriptions.
+Some of those features are mentioned in \fB\%screen\fP(1) or
+\fBtmux\fP(1).
+.PP
+.I "XTerm Control Sequences"
+provides further information on the \fB\%xterm\fP(1) features
+that are used in these extended capabilities.