diff options
Diffstat (limited to 'doc/html/man/user_caps.5.html')
-rw-r--r-- | doc/html/man/user_caps.5.html | 140 |
1 files changed, 74 insertions, 66 deletions
diff --git a/doc/html/man/user_caps.5.html b/doc/html/man/user_caps.5.html index 95bb74d..0fd1f15 100644 --- a/doc/html/man/user_caps.5.html +++ b/doc/html/man/user_caps.5.html @@ -1,6 +1,6 @@ -<!-- +<!-- **************************************************************************** - * Copyright 2018-2019,2020 Thomas E. Dickey * + * Copyright 2018-2020,2021 Thomas E. Dickey * * Copyright 2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: user_caps.5,v 1.12 2020/02/02 23:34:34 tom Exp @ + * @Id: user_caps.5,v 1.17 2021/06/17 21:30:22 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> @@ -57,20 +57,20 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> </PRE><H3><a name="h3-Background">Background</a></H3><PRE> - Before ncurses 5.0, terminfo databases used a <EM>fixed</EM> <EM>repertoire</EM> of ter- - minal 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. + Before ncurses 5.0, terminfo databases used a <EM>fixed</EM> <EM>repertoire</EM> 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. Most of the <EM>extensions</EM> 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 ter- - minfo 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: + 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: - <STRONG>o</STRONG> The <EM>binary</EM> <EM>format</EM> itself is not described in the X/Open Curses doc- - umentation. Only the <EM>source</EM> <EM>format</EM> is described. + <STRONG>o</STRONG> The <EM>binary</EM> <EM>format</EM> itself is not described in the X/Open Curses + documentation. Only the <EM>source</EM> <EM>format</EM> is described. Library developers rely upon the SVr4 documentation, and reverse- engineering the compiled terminfo files to match the binary format. @@ -91,9 +91,9 @@ While ncurses' 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, ncurses can be con- - figured with tables which match the terminal databases for AIX, HP- - UX or OSF/1, rather than the default Solaris-like configuration. + list published by X/Open Curses. For example, ncurses can be + configured with tables which match the terminal databases for AIX, + HP-UX or OSF/1, rather than the default Solaris-like configuration. <STRONG>o</STRONG> In SVr4 curses and ncurses, the terminal database is defined at compile-time using a text file which lists the different terminal @@ -101,9 +101,9 @@ In principle, the text-file can be extended, but doing this requires recompiling and reinstalling the library. The text-file - used in ncurses for terminal capabilities includes details for var- - ious systems past the documented X/Open Curses features. For exam- - ple, ncurses supports these capabilities in each configuration: + used in ncurses for terminal capabilities includes details for + various systems past the documented X/Open Curses features. For + example, ncurses supports these capabilities in each configuration: memory_lock (meml) lock memory above cursor @@ -115,16 +115,16 @@ (box1) box characters primary set The memory lock/unlock capabilities were included because they were - used in the X11R6 terminal description for <STRONG>xterm</STRONG>. The <EM>box1</EM> capa- - bility is used in tic to help with terminal descriptions written - for AIX. + used in the X11R6 terminal description for <STRONG>xterm</STRONG>. The <EM>box1</EM> + capability is used in tic to help with terminal descriptions + written for AIX. During the 1990s, some users were reluctant to use terminfo in spite of its performance advantages over termcap: - <STRONG>o</STRONG> The fixed repertoire prevented users from adding features for unan- - ticipated terminal improvements (or required them to reuse existing - capabilities as a workaround). + <STRONG>o</STRONG> The fixed repertoire prevented users from adding features for + unanticipated terminal improvements (or required them to reuse + existing capabilities as a workaround). <STRONG>o</STRONG> The limitation to 16-bit signed integers was also mentioned. Because termcap stores everything as a string, it could represent @@ -132,10 +132,10 @@ Although termcap's extensibility was rarely used (it was never the <EM>speaker</EM> who had actually used the feature), the criticism had a point. - ncurses 5.0 provided a way to detect nonstandard capabilities, deter- - mine their type and optionally store and retrieve them in a way which - did not interfere with other applications. These are referred to as - <EM>user-defined</EM> <EM>capabilities</EM> because no modifications to the toolset's + ncurses 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 <EM>user-defined</EM> <EM>capabilities</EM> because no modifications to the toolset's predefined capability names are needed. The ncurses utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x" @@ -144,8 +144,8 @@ same purpose. When compiling a terminal database, if "-x" is set, <STRONG>tic</STRONG> will store a - user-defined capability if the capability name is not one of the prede- - fined names. + user-defined capability if the capability name is not one of the + predefined names. Because ncurses provides a termcap library interface, these user- defined capabilities may be visible to termcap applications: @@ -153,8 +153,8 @@ <STRONG>o</STRONG> The termcap interface (like all implementations of termcap) requires that the capability names are 2-characters. - When the capability is simple enough for use in a termcap applica- - tion, it is provided as a 2-character name. + When the capability is simple enough for use in a termcap + application, it is provided as a 2-character name. <STRONG>o</STRONG> There are other user-defined capabilities which refer to features not usable in termcap, e.g., parameterized strings that use more @@ -163,17 +163,17 @@ only capability names with 3 or more characters. <STRONG>o</STRONG> Some terminals can send distinct strings for special keys (cursor-, - keypad- or function-keys) depending on modifier keys (shift, con- - trol, etc.). While terminfo and termcap have a set of 60 prede- - fined function-key names, to which a series of keys can be - assigned, that is insufficient for more than a dozen keys multi- - plied by more than a couple of modifier combinations. The ncurses - database uses a convention based on <STRONG>xterm</STRONG> to provide extended spe- - cial-key names. + 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 + ncurses database uses a convention based on <STRONG>xterm</STRONG> to provide + extended special-key names. Fitting that into termcap's limitation of 2-character names would - be pointless. These extended keys are available only with ter- - minfo. + be pointless. These extended keys are available only with + terminfo. </PRE><H3><a name="h3-Recognized-capabilities">Recognized capabilities</a></H3><PRE> @@ -228,10 +228,10 @@ i.e., one bit per color. U8 <EM>number</EM>, asserts that ncurses must use Unicode values for line- - drawing characters, and that it should ignore the alternate char- - acter set capabilities when the locale uses UTF-8 encoding. For - more information, see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG> in - <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. + 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 <STRONG>NCURSES_NO_UTF8_ACS</STRONG> + in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. Set this capability to a nonzero value to enable it. @@ -243,13 +243,13 @@ certain modes) moves the mouse, handles the characters sent back by the terminal to tell it what was done with the mouse. - The mouse protocol is enabled when the <EM>mask</EM> passed in the <STRONG>mouse-</STRONG> - <STRONG>mask</STRONG> function is nonzero. By default, ncurses handles the + The mouse protocol is enabled when the <EM>mask</EM> passed in the + <STRONG>mousemask</STRONG> function is nonzero. By default, ncurses handles the responses for the X11 xterm mouse protocol. It also knows about the <EM>SGR</EM> <EM>1006</EM> 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 confu- - sion would result. + is used, because the responses are enough alike that only + confusion would result. The <STRONG>XM</STRONG> capability has a single parameter. If nonzero, the mouse protocol should be enabled. If zero, the mouse protocol should @@ -259,14 +259,14 @@ 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 descrip- - tions. + mouse protocols which can be used in customized terminal + descriptions. The terminal database building blocks for this mouse feature also have an experimental capability <EM>xm</EM>. The "xm" capability describes the mouse response. Currently there is no interpreter - which would use this information to make the mouse support com- - pletely data-driven. + which would use this information to make the mouse support + completely data-driven. <EM>xm</EM> shows the format of the mouse responses. In this experimental capability, the parameters are @@ -287,8 +287,8 @@ <EM>p8</EM> x-ordinate ending region - Here are examples from the terminal database for the most com- - monly used xterm mouse protocols: + Here are examples from the terminal database for the most + commonly used xterm mouse protocols: xterm+x11mouse|X11 xterm mouse protocol, kmous=\E[M, XM=\E[?1000%?%p1%{1}%=%th%el%;, @@ -306,15 +306,15 @@ </PRE><H3><a name="h3-Extended-key-definitions">Extended key-definitions</a></H3><PRE> - Several terminals provide the ability to send distinct strings for com- - binations of modified special keys. There is no standard for what + 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. Since 1999, <STRONG>xterm</STRONG> has supported <EM>shift</EM>, <EM>control</EM>, <EM>alt</EM>, and <EM>meta</EM> modifiers which produce distinct special-key strings. In a terminal description, ncurses has no special knowledge of the modifiers used. Applications - can use the <EM>naming</EM> <EM>convention</EM> established for <STRONG>xterm</STRONG> to find these spe- - cial keys in the terminal description. + can use the <EM>naming</EM> <EM>convention</EM> established for <STRONG>xterm</STRONG> to find these + special keys in the terminal description. Starting with the curses convention that <EM>key</EM> <EM>names</EM> begin with "k" and that shifted special keys are an uppercase name, ncurses' terminal @@ -356,21 +356,29 @@ which ncurses will allocate at runtime to <EM>key-codes</EM>. To use these keys in an ncurses program, an application could do this: - <STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their val- - ues, and + <STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their + values, and <STRONG>o</STRONG> given the list of values, ask <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> for the <EM>key-code</EM> which would be returned for those keys by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - The "-x" extension feature of <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> has been adopted in Net- - BSD curses. That implementation stores user-defined capabilities, but - makes no use of these capabilities itself. + The "-x" extension feature of <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> has been adopted in + NetBSD curses. That implementation stores user-defined capabilities, + but makes no use of these capabilities itself. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>. + <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>. + + The terminal database section <EM>NCURSES</EM> <EM>USER-DEFINABLE</EM> <EM>CAPABILITIES</EM> + summarizes commonly-used user-defined capabilities which are used in + the terminal descriptions. Some of those features are mentioned in + <STRONG>screen(1)</STRONG> or <STRONG>tmux(1)</STRONG>. + + <EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM> provides further information on the <STRONG>xterm</STRONG> + features which are used in these extended capabilities. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> |