X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fuser_caps.5;h=b43e218f376d7921d799c632dccc85e87e0b46b4;hb=6662c1ccb49cb09d0f2cec2ec6150410a0fd0f7f;hp=c90aee54e8f979798362af0ae97516a4ad6efe85;hpb=8f6d94b8d6211a2323caef53fa4c96c475ec9a62;p=ncurses.git

diff --git a/man/user_caps.5 b/man/user_caps.5
index c90aee54..b43e218f 100644
--- a/man/user_caps.5
+++ b/man/user_caps.5
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 2017,2018 Free Software Foundation, Inc.                   *
+.\" Copyright 2018-2021,2022 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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: user_caps.5,v 1.9 2018/07/28 22:05:23 tom Exp $
+.\" $Id: user_caps.5,v 1.22 2022/07/03 20:01:04 tom Exp $
 .TH user_caps 5
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -123,9 +124,9 @@ 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.
+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. 
+written for AIX.
 .PP
 During the 1990s, some users were reluctant to use terminfo
 in spite of its performance advantages over termcap:
@@ -180,7 +181,7 @@ 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 \fBxterm\fP to
+The ncurses 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
@@ -206,9 +207,15 @@ the terminal.
 .IP
 The command \*(``\fBtput clear\fP\*('' does the same thing.
 .TP 3
+NQ
+used to suppress a consistency check in @TIC@ for the ncurses 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,
-to assert that the
+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.
@@ -257,7 +264,85 @@ Set this capability to a nonzero value to enable it.
 XM
 \fIstring\fP,
 override ncurses's built-in string which
-enables/disables \fBxterm\fP mouse mode.
+enables/disables \fBxterm\fP(1) mouse mode.
+.IP
+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 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, ncurses 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.
+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.
+.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=\\E[M, XM=\\E[?1000%?%p1%{1}%=%th%el%;,
+          xm=\\E[M
+             %?%p4%t%p3%e%{3}%;%'\ '%+%c
+             %p2%'!'%+%c
+             %p1%'!'%+%c,
+
+  xterm+sm+1006|xterm SGR-mouse,
+          kmous=\\E[<, XM=\\E[?1006;1000%?%p1%{1}%=%th%el%;,
+          xm=\\E[<%i%p3%d;
+             %p1%d;
+             %p2%d;
+             %?%p4%tM%em%;,
+.fi
 .
 .SS Extended key-definitions
 .PP
@@ -265,7 +350,7 @@ 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 has supported
+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, ncurses has no special knowledge of the
@@ -280,7 +365,7 @@ ncurses' terminal database defines these names to which a suffix is added:
 .TS
 tab(/) ;
 l l .
-\fIName\fR/\fIDescription\fR
+\fBName\fP/\fBDescription\fP
 _
 kDC/special form of kdch1 (delete character)
 kDN/special form of kcud1 (cursor down)
@@ -299,7 +384,7 @@ These are the suffixes used to denote the modifiers:
 .TS
 tab(/) ;
 l l .
-\fIValue\fR/\fIDescription\fR
+\fBValue\fP/\fBDescription\fP
 _
 2/Shift
 3/Alt
@@ -330,16 +415,29 @@ 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).
 .PP
+.\"
 .SH PORTABILITY
 .PP
 The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP
 has been adopted in NetBSD curses.
 That implementation stores user-defined capabilities,
 but makes no use of these capabilities itself.
+.\"
 .SH SEE ALSO
 .PP
-\fB@TIC@\fR(1M),
-\fB@INFOCMP@\fR(1M).
+\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 \fBscreen\fP(1) or \fBtmux\fP(1).
+.PP
+.I "XTerm Control Sequences"
+provides further information on the \fBxterm\fP(1) features
+which are used in these extended capabilities.
+.\"
 .SH AUTHORS
 .PP
 Thomas E. Dickey