[PATCH 07/12] man/curs_getch.3x: Recast description of keypad mode.

[G. Branden Robinson]

Attempt to make it more clear and to more obviously link it with other
curses concepts and (terminfo) data.
---
 man/curs_getch.3x | 62 +++++++++++++++++++++++++++++++----------------
 1 file changed, 41 insertions(+), 21 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 956d1f0ef..3bd28500d 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -221,35 +221,55 @@ .SS "Keypad Mode"
 waiting to see if,
 and how soon,
 further input arrives.
-When
-.I curses
-reads such an ambiguous character,
-it sets a timer.
-If the remainder of the sequence does not arrive within the designated
-time,
+.bP
+If the escape sequence
+matches a string capability defining a function key
+for the terminal type
+(such as
+.B \%key_home
+.RB \%( khome )
+or
+.B \%key_up
+.RB \%( kuu1 )),
 .B \%wgetch
-returns the prefix character;
-otherwise,
-it returns the function key code corresponding to the unique sequence
+returns the function key code corresponding to the unique sequence
 defined by the terminal.
+.bP
+If the escape sequence matches no function keys
+defined for the terminal type,
+.B \%wgetch
+returns the code of the last
+(most recent)
+character it has read.
+.bP
+If
+.B \%wgetch
+cannot decide the validity of the input as a function key
+because it has not read enough characters to disambiguate it,
+the function waits until it has this information or the
+.IR "escape delay" ","
+configured by the global variable
+.I \%ESCDELAY
+(an extension;
+see section \*(``EXTENSIONS\*('' below)
+or the environment variable of the same name
+(see section \*(``ENVIRONMENT\*('' of \fB\%ncurses\fP(3X)),
+also an extension,
+elapses.
+.PP
 Consequently,
 a user of a
 .I curses
-application may experience a delay after the escape key is pressed
+application that employs keypad mode
+may experience a pause or \*(``hang\*(''
+after the escape key is pressed
 while
 .I curses
-disambiguates the input;
-see section \*(``EXTENSIONS\*('' below.
+collects sufficient characters to disambiguate the input.
 If the window is in \*(``no time-out\*('' mode,
-the timer does not expire;
-it is an infinite
-(or very large)
-value.
-See \fB\%notimeout\fP(3X).
-Because function key sequences usually begin with ESC,
-the terminal may appear to hang in no time-out mode after the user
-presses the escape key.
-Generally,
+the escape delay is effectively infinite;
+see \fB\%notimeout\fP(3X).
+In the event of such a pause,
 further typing \*(``awakens\*(''
 .IR curses "."
 .SS "Ungetting Characters"
-- 
2.30.2

signature.asc
Description: PGP signature