Content: * Say when ncurses 5.0 was released; several other dates are stated in the same paragraph, and adding this observation reveals how long some terminfo application developers have been dragging their feet. * Explain how the compiled terminfo entry format permitted (validation of) binary compatibility. * Refer to "color channels", not "components". * Clarify cross reference to the lengthy ncurses(3X) page. * Clarify reference to terminfo database source file.
Style: * Protect whatever "@INFOCMP@" expands to from hyphenation. * Protect whatever "@TIC@" expands to from hyphenation. * Specify hyphenation breakpoint in "terminfo". * Unhyphenate "reverse engineering" when used as a verb. * Fix solecisms in hyponymy; a capability is not the same thing as its value. * Employ Oxford comma. * Use "that", not "which", with restrictive subordinate clauses.[1] * Set terminfo capability names and their cap-codes in bold, not roman. * Set "termcap" and "terminfo" in italics, not roman. * In list of recognized user-defined capabilities, present capability type in parentheses. * Set "SGR 1006" in roman, not italics. * Set xterm(1) man page (and command) cross references in italics, not bold, since it is a "foreign" project from ncurses's perspective, like emacs(1) or jove(1). * Recast. Markup: * Favor man(7) font style macros over *roff font selection escape sequences, except for man page cross references (because man/make_sed.sh recognizes only certain patterns when rewriting such cross references) and terms in the "NAME" section (because the generated edit_man.sh script expects font selection escape sequences when scraping terms thence to gather names for man page aliases). * Use paragraphing macro for vertical spacing in displayed example. * Bracket displayed example with `EX`/`EE` macros. groff (and Ninth Edition Unix) sets the material within in a monospaced font on typesetters. man/man_db.renames.in: Add "color_content.3x", "init_color.3x", and "mousemask.3x". [1] Authorities: * https://owl.purdue.edu/owl/general_writing/grammar/that_vs_which.html * https://www.merriam-webster.com/grammar/when-to-use-that-and-which * https://www.oxbridgeediting.co.uk/blog/which-vs-that-understanding-the-difference/ --- man/man_db.renames.in | 3 + man/user_caps.5 | 518 ++++++++++++++++++++++++++++-------------- 2 files changed, 352 insertions(+), 169 deletions(-) diff --git a/man/man_db.renames.in b/man/man_db.renames.in index 0cac2a8a8..9b3a44303 100644 --- a/man/man_db.renames.in +++ b/man/man_db.renames.in @@ -184,6 +184,7 @@ bkgrnd.3x bkgrnd.3ncurses cbreak.3x cbreak.3ncurses clearok.3x clearok.3ncurses clrtoeol.3x clrtoeol.3ncurses +color_content.3x color_content.3ncurses curs_set.3x curs_set.3ncurses curscr.3x curscr.3ncurses curses_trace.3x curses_trace.3ncurses @@ -216,6 +217,7 @@ idlok.3x idlok.3ncurses immedok.3x immedok.3ncurses in_wch.3x in_wch.3ncurses inch.3x inch.3ncurses +init_color.3x init_color.3ncurses initscr.3x initscr.3ncurses is_cbreak.3x is_cbreak.3ncurses is_scrollok.3x is_scrollok.3ncurses @@ -226,6 +228,7 @@ killwchar.3x killwchar.3ncurses leaveok.3x leaveok.3ncurses longname.3x longname.3ncurses meta.3x meta.3ncurses +mousemask.3x mousemask.3ncurses move.3x move.3ncurses mvcur.3x mvcur.3ncurses mvwin.3x mvwin.3ncurses diff --git a/man/user_caps.5 b/man/user_caps.5 index e648878e8..947254f0a 100644 --- a/man/user_caps.5 +++ b/man/user_caps.5 @@ -47,17 +47,22 @@ .. .SH NAME user_caps \- -user-defined \fIterminfo\fR capability format +user-defined \%\fIterm\%info\fP 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), +Prior to +.I \%ncurses +5.0 (1999), +.I \%term\%info +databases used a +.I "fixed repertoire" +of terminal capabilities designed +for the SVr2 terminal database in 1984, +added to in stages through SVr4 (1989), and standardized in X/Open Curses starting in 1995. .\" That date is a surmise based on the capability list appearing in .\" Issue 4, Version 2 (1996). That list is not in man page format in @@ -77,124 +82,201 @@ .SS Background .\" (hinting that something may have been in the initial releases of System V) .\" but the first release with tic appears to be SVr2 in 1984. .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: +Most such additions to this fixed repertoire +suppelmented the tables of Boolean, +numeric, +and string capabilities. +Rather than changing the meaning of an existing capability, +a new name was added. +The +.I \%term\%info +database uses a binary format; +binary compatibility was ensured +by using a header +that counted the number of items in the tables +for each type of capability. +Because each +.I curses +vendor extended the standard capability lists in distinct ways, +a library could be programmed to recognize only compiled +.I \%term\%info +entries that it was prepared to interpret. +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. +X/Open Curses describes only the +.I source +format, +not its +.I binary +representation on disk. .IP -Library developers rely upon the SVr4 documentation, -and reverse-engineering the compiled terminfo files to match the binary format. +Library developers rely upon SVr4 documentation +and reverse engineering of compiled +.I \%term\%info +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, +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. +The SVr2 format cannot represent very large numeric capability values, +nor can it represent large numbers of key definitions, +as are required to distinguish multiple modifier keys used +in combination with a function key. .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. +Although they +.I may +provide all of the standard capability names, +each arranges its table entries differently +because some features were added as needed, +while others were added +\(em out of order \(em +for X/Open Curses conformance. .IP While .IR ncurses 's capability repertoire is closest to that of Solaris, -the latter's +the set of capabilities supported by +each vendor's .I \%term\%info database differs 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, +.I \%ncurses +can be configured +with tables that 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. +In SVr4 +.I curses +and +.IR \%ncurses "," +the terminal database is defined at compile time +by interpolating a text file +that 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: +In principle, +the text file can be extended, +but doing so requires recompiling and reinstalling the library. +The text file used by +.I \%ncurses +for terminal capabilities includes details of extensions +to X/Open Curses +made by various systems. +For example, +.I \%ncurses +supports the following nonstandard capabilities in each configuration. .RS 8 .TP 5 -memory_lock -(meml) +.B memory_lock +.RB ( meml ) lock memory above cursor .TP 5 -memory_unlock -(memu) +.B memory_unlock +.RB ( memu ) unlock memory .TP 5 -box_chars_1 -(box1) +.B box_chars_1 +.RB ( 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. +in the X11R6 terminal description for \fIxterm\fP(1). +.B \%@TIC@ +uses the +.B box1 +capability to cope 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: +During the 1990s, +some application developers were reluctant to use +.I \%term\%info +in spite of its performance +(and other) +advantages over +.IR termcap "." .bP -The fixed repertoire prevented users from adding features -for unanticipated terminal improvements +The fixed repertoire prevented users from adding support +for terminal features unanticipated by X/Open Curses (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, +Because +.I 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), +Although +.IR termcap 's +extensibility was rarely used +\(em the claimant was never an implementor +who had actually exercised it \(em 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. +.I \%ncurses +5.0 provided a way to detect nonstandard capabilities, +to determine their type, +and to optionally store and retrieve them +in a way that did not interfere with other applications. .I ncurses terms these .I "user-defined capabilities" because no modifications to the standard capability list are needed. .PP -The \fI\%ncurses\fP utilities \fB@TIC@\fP and \fB@INFOCMP@\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. +The +.I \%ncurses +utilities +.B \%@TIC@ +and +.B \%@INFOCMP@ +have a command-line option \*(``\-x\*('' +to control whether the nonstandard capabilities +are stored or retrieved. +.I \%ncurses +provides \fBuse_extended_names\fP(3X) to programs for the same purpose. .PP -When compiling a terminal database, if \*(``\-x\*('' is set, -\fB@TIC@\fP stores a user-defined capability +When compiling a terminal database, if \*(``\-x\*('' is used, +.B \%@TIC@ +stores a user-defined capability if the capability name is not standard. .PP -Because \fI\%ncurses\fP provides a termcap library interface, -these user-defined capabilities may be visible to termcap applications: +Because +.I \%ncurses +provides a +.I termcap +library interface, +these user-defined capabilities may be visible to +.I termcap +applications. .bP -The termcap interface (like all implementations of termcap) -requires that the capability names are 2-characters. +The +.I termcap +interface +(like all implementations of +.IR termcap ) +restricts capability names to two characters. .IP -When the capability is simple enough for use in a termcap application, -it is provided as a 2-character name. +When the capability is simple enough for use in a +.I termcap +application, +it is provided as a two-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. +Other user-defined capabilities employ features not usable in +.IR termcap "," +such as parameterized strings that use more than two parameters +or require more powerful expressions than +.I termcap +supports. +Such capabilities should, +in the +.I \%term\%info +database, +have names at least three characters in length. .bP Some terminals can send distinct strings for special keys (cursor-, keypad- or function-keys) depending on modifier keys (shift, control, etc.). @@ -206,128 +288,215 @@ .SS Background 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) +The +.I \%ncurses +database uses a convention based on \fIxterm\fP(1) to provide extended special-key names. .IP -Fitting that into termcap's limitation of 2-character names +Fitting that into +.IR termcap 's +limitation of 2-character names would be pointless. -These extended keys are available only with terminfo. +These extended keys are available only with +.IR \%term\%info "." .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: +The +.I \%ncurses +library employs user-definable capabilities. +While the +.I \%term\%info +database may have other extensions, +.I \%ncurses +makes explicit checks for the following. .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. +.B AX +(Boolean) +asserts that the terminal interprets SGR 39 and SGR 49 +by resetting the foreground and background colors, +respectively, +to the default. .IP -This is a feature recognized by the \fBscreen\fP program as well. +\fBscreen\fP(1) +recognizes this capability 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. +.B E3 +(string) +tells an application 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. +The command +.RB \*(`` "tput clear" \*('' +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 +.B NQ +(Boolean) +suppresses a consistency check in +.B \%@TIC@ +for the +.I \%ncurses +string capabilities +.B user6 +.RB ( u6 ) +through +.B user9 +.RB ( u9 ), +which tell an application 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, +.B RGB +(Boolean, +numeric, +or +string) +asserts that the +.B \%set_a_foreground +.RB ( setaf ) +and +.B \%set_a_background +.RB ( setab ) +capabilities employ +.IR "direct colors" "," 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. +This capability allows \fBcolor_content\fP(3X) +to return appropriate values +without requiring the application +to initialize colors using \fBinit_color\fP(3X). .IP -The capability type determines the values which \fI\%ncurses\fP sees: +The capability type determines the values +.I \%ncurses +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, +Boolean +implies that the number of bits for red, +green, +and blue are the same. +Starting with the value of the capability +.B max_colors +.RB \%( colors ; +.I termcap: +.BR co ), +.I \%ncurses +adds two, +divides the sum by three, and assigns the result to red, -green and blue in that order. +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. +If the number of bits needed for the number of colors +is not a multiple of three, +the blue (and green) color channels 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. +numeric +tells +.I \%ncurses +what result to add to red, +green, +and blue. +If +.I \%ncurses +runs out of bits, +blue (and green) lose just as in the Boolean case. .TP 3 -\fIstring\fP -explicitly list the number of bits used for red, green and blue components +string +specify the quantity of bits used for +red, +green, +and blue color channels 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 +applications that make assumptions +about the number of bits per color channel 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. +As a trivial case, +one could define +.B RGB#1 +to represent the standard eight ANSI\ X3.64/ECMA-48/ISO\ 6429 colors +using one bit per color channel. .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 +.B U8 +(numeric) +asserts whether +.I \%ncurses +must use Unicode values for line-drawing characters, +and that it should ignore the alternate character set (ACS) 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). +See the discussion of +.B \%NCURSES_NO_UTF8_ACS +in section \*(``ENVIRONMENT\*('' of \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. +.B XM +(string) +override +.IR \%ncurses 's +built-in string that directs \fIxterm\fP(1) +to enable or disable 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. +.I \%ncurses +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 the application what was done with the mouse. .IP -The mouse protocol is enabled when -the \fImask\fP passed in the \fBmousemask\fP function is nonzero. +The mouse protocol is enabled +when the +.I \fImask\fP +argument to the \fBmousemask\fP(3X) 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, +.I \%ncurses +handles the responses for the X11 +.I xterm +mouse protocol. +It also knows about the SGR\ 1006 +.I xterm +mouse protocol, +but must to be told to look for it specifically. +.I \%ncurses +is not be able to guess which of the two modes 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, +The +.B XM +capability has a single numeric parameter. +If nonzero, +the mouse protocol should be enabled. +If zero, +the mouse protocol should be disabled. +.I \%ncurses +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. +If so, +it expects the responses to use the SGR\ 1006 +.I 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. +The +.I xterm +mouse protocol is used by other terminal emulators. +The terminal database uses building blocks for the various +.I xterm +mouse protocols usable 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. +The terminal database building blocks for this mouse feature +also have an experimental capability, +.BR xm "," +that describes the mouse response. +No known interpreter uses this information, +which could make mouse support completely data-driven. .IP -\fIxm\fP shows the format of the mouse responses. -In this experimental capability, the parameters are +.B xm +shows the format of the mouse responses. +In this experimental capability, +the parameters are as follows. .RS 5 .TP 5 .I p1 @@ -356,8 +525,10 @@ .SS "Recognized Capabilities" .RE .IP Here are examples from the terminal database for the most commonly used -xterm mouse protocols: +.I xterm +mouse protocols. .IP +.EX .nf xterm+x11mouse|X11 xterm mouse protocol, kmous=\eE[M, XM=\eE[?1000%?%p1%{1}%=%th%el%;, @@ -365,7 +536,7 @@ .SS "Recognized Capabilities" %?%p4%t%p3%e%{3}%;%'\ '%+%c %p2%'!'%+%c %p1%'!'%+%c, - +.IP xterm+sm+1006|xterm SGR-mouse, kmous=\eE[<, XM=\eE[?1006;1000%?%p1%{1}%=%th%el%;, xm=\eE[<%i%p3%d; @@ -373,18 +544,20 @@ .SS "Recognized Capabilities" %p2%d; %?%p4%tM%em%;, .fi +.EE . .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 +Since 1999, \fIxterm\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 +Applications can use the \fInaming convention\fP established for +\fIxterm\fP to find these special keys in the terminal description. .PP Starting with the @@ -471,27 +644,34 @@ .SS "Extended Key Definitions" would be returned for those keys by \fBwgetch\fP(3X). .\" .SH PORTABILITY -The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP -has been adopted in NetBSD curses. +The \*(``\-x\*('' extension feature of +.B \%@TIC@ +and +.B \%@INFOCMP@ +has been adopted in NetBSD +.IR 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) +beginning with +.I \%ncurses +5.0 (1999) .\" .SH SEE ALSO \fB\%@INFOCMP@\fP(1M), \fB\%@TIC@\fP(1M) .PP -The terminal database section -.I "NCURSES USER-DEFINABLE CAPABILITIES" +In the source form of the terminal database, +.IR \%terminfo.src "," +the section \*(``NCURSES USER-DEFINABLE CAPABILITIES\*(''. summarizes commonly-used user-defined capabilities -which are used in the terminal descriptions. +employed 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 +provides further information on the \fI\%xterm\fP(1) features that are used in these extended capabilities. -- 2.30.2
signature.asc
Description: PGP signature
