[PATCH 10/17] man/curs_getch.3x: Revise (2/8).

[G. Branden Robinson]

Revise discussion of "keypad mode".

Content:
* Introduce the subject and its terminology.  Describe the dichotomy
  between ordinary (non-keypad) and keypad codes.  Add cross reference
  to ascii(7) man page.  Reference ECMA-6 and ECMA-48 as well, and add
  them to the "SEE ALSO" section with URLs.  Introduce curses's
  definition of the term "function key", which is broader than the
  conventional understanding of F1, F2, and so on.
* Postpone discussion of "ESCDELAY" because it is a nonstandard
  extension.

Style:
* Italicize "predefined function keys" from "user-defined function keys"
  to flag them as jargon/terms of art.
* Recast explanation of ESC and function key code sequence
  disambiguation process.
* Attempt to guide the perplexed.

Markup:
* Define `:` *roff string to (portably) enable groff (and formatters
  claiming compatibility with it) to break URLs without hyphens.
* 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).
---
 man/curs_getch.3x | 133 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 100 insertions(+), 33 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 844d3e5a6..764538c63 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -41,6 +41,9 @@
 .el   .ds '' ""
 .\}
 .
+.ie \n(.g .ds : \:
+.el       .ds : \" empty
+.
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
@@ -149,39 +152,93 @@ .SS "Reading Characters"
 (line feed)
 instead.
 .SS "Keypad Mode"
-If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for
-that function key is returned instead of the raw characters:
+To
+.IR curses ,
+key strokes not from the alphabetic section of the keyboard
+(those corresponding to the ECMA-6 character set\(emsee
+\fIascii\fP(7)\(emoptionally modified by either the control or shift
+keys)
+are treated as
+.I function
+keys.
+(In
+.IR curses ,
+the term \*(``function key\*('' includes but is not limited to keycaps
+engraved with \*(``F1\*('',
+\*(``PF1\*('',
+and so on.)
+If the window is in keypad mode,
+these produce a numeric code corresponding to the
+.B KEY_
+symbols listed in subsection \*(``Predefined Key Codes\*('' below;
+otherwise,
+they transmit a sequence of codes typically starting with the escape
+character,
+and which must be collected with multiple
+.B \%wgetch
+calls.
 .bP
-The predefined function
-keys are listed in \fB<curses.h>\fP as macros with values outside the range
-of 8-bit characters.
-Their names begin with \fBKEY_\fP.
+The
+.I \%curses.h
+header file declares many
+.I "predefined function keys"
+whose names begin with
+.BR KEY_ ;
+these object-like macros have values outside the range of eight-bit
+character codes.
 .bP
-Other (user-defined) function keys which may be defined
-using \fBdefine_key\fP(3X)
-have no names, but also are expected to have values outside the range of
-8-bit characters.
+In
+.IR \%ncurses ,
+.I "user-defined function keys"
+are configured with \fBdefine_key\fP(3X);
+they have no names,
+but are also expected to have values outside the range of eight-bit
+codes.
 .PP
-Thus, a variable
-intended to hold the return value of a function key must be of short size or
-larger.
+A variable intended to hold a function key code must thus be of type
+.I short
+or larger.
 .PP
-When a character that could be the beginning of a function key is received
-(which, on modern terminals, means an escape character),
-\fBcurses\fP sets a timer.
-If the remainder of the sequence does not come in within the designated
-time, the character is passed through;
-otherwise, the function key value is returned.
-For this reason, many terminals experience a delay between the time
-a user presses the escape key and the escape is returned to the program.
-.PP
-In \fI\%ncurses\fP, the timer normally expires after
-the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)).
-If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire;
-it is an infinite (or very large) value.
-Because function keys usually begin with an escape character,
-the terminal may appear to hang in notimeout mode after pressing the escape key
-until another key is pressed.
+Most terminals one encounters follow the ECMA-48 standard insofar as
+their function keys produce character sequences prefixed with the
+escape character ESC.
+This fact implies that
+.I curses
+cannot know whether the terminal has sent an ESC key stroke or the
+beginning of a function key's character sequence without 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,
+.B \%wgetch
+returns the prefix character;
+otherwise,
+it returns the function key code corresponding to the unique sequence
+defined by the terminal.
+Consequently,
+a user of a
+.I curses
+application may experience a delay after pressing ESC while
+.I curses
+disambiguates the input.
+See section \*(``EXTENSIONS\*('' below.
+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 an escape character,
+the terminal may appear to hang in no time-out mode after the user has
+pressed ESC.
+Generally,
+further typing \*(``awakens\*(''
+.I curses.
 .SS "Ungetting Characters"
 The \fBungetch\fP routine places \fIch\fP back onto the input queue to be
 returned by the next call to \fBwgetch\fP.
@@ -494,8 +551,18 @@ .SH SEE ALSO
 \fB\%curs_outopts\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_variables\fP(3X),
-\fB\%resizeterm\fP(3X)
+\fB\%resizeterm\fP(3X),
+\fB\%ascii\fP(7)
+.PP
+\fB\%curs_get_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+ECMA-6 \*(``7-bit coded Character Set\*(''
+\%<https://\*:ecma\-international\*:.org/\
+\*:publications\-and\-standards/\*:standards/\*:ecma\-6/>
 .PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fB\%curs_get_wch\fP(3X).
+ECMA-48 \*(``Control Functions for Coded Character Sets\*(''
+\%<https://\*:ecma\-international\*:.org/\
+\*:publications\-and\-standards/\*:standards/\*:ecma\-48/>
-- 
2.30.2

signature.asc
Description: PGP signature