[PATCH 048/100] man/ncurses.3x: Revise "ENVIRONMENT" section, ESCDELAY (4/21).

[G. Branden Robinson]

---
 man/ncurses.3x | 56 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 35 insertions(+), 21 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 9b84571e3..66dceb1b3 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1125,32 +1125,46 @@ .SS "\fICOLUMNS\fP"
 to match the screen size obtained from system calls or the terminal
 database.
 .SS "\fIESCDELAY\fP"
-Specifies the total time,
-in milliseconds,
-for which \fI\%ncurses\fP will await a character sequence,
-e.g.,
-a function key.
-The default value, 1000 milliseconds, is enough for most uses.
-However, it is made a variable to accommodate unusual applications.
+For
+.I curses
+to distinguish the ESC character resulting from a user's press of the
+\*(``Escape\*('' key on the input device from one beginning an
+.I "escape sequence"
+(as commonly produced by function keys),
+it waits after receiving the escape character to see if further
+characters are available on the input stream within a short interval.
+A global variable
+.B \%ESCDELAY
+stores this interval in milliseconds.
+The default value of 1000
+(one second)
+is adequate for most uses.
+This environment variable overrides it.
 .PP
 The most common instance where you may wish to change this value
-is to work with slow hosts, e.g., running on a network.
-If the host cannot read characters rapidly enough, it will have the same
-effect as if the terminal did not send characters rapidly enough.
-The library will still see a timeout.
-.PP
-Note that xterm mouse events are built up from character sequences
-received from the xterm.
-If your application makes heavy use of multiple-clicking, you may
-wish to lengthen this default value because the timeout applies
-to the composed multi-click event as well as the individual clicks.
-.PP
-In addition to the environment variable,
-this implementation provides a global variable with the same name.
-Portable applications should not rely upon the presence of \fB\%ESCDELAY\fP
+is to work with a remote host over a slow communication channel.
+If the host running a
+.I curses
+application does not receive the characters of an escape sequence in a
+timely manner,
+the library can interpret them as multiple key stroke events.
+.PP
+\fI\%xterm\fP(1) mouse events are a form of escape sequence;
+therefore,
+if your application makes heavy use of multiple-clicking,
+you may wish to lengthen the default value because the delay applies
+to the composite multi-click event as well as the individual clicks.
+.PP
+Portable applications should not rely upon the presence of
+.B \%ESCDELAY
 in either form,
 but setting the environment variable rather than the global variable
 does not create problems when compiling an application.
+.PP
+If \fB\%keypad\fP(3X) is disabled for the
+.I curses
+window receiving input,
+a program must disambiguate escape sequences itself.
 .SS "\fIHOME\fP"
 Tells \fI\%ncurses\fP where your home directory is.
 That is where it may read and write auxiliary terminal descriptions:
-- 
2.30.2

signature.asc
Description: PGP signature