[PATCH 16/45] man/curs_inopts.3x: Recast to accommodate wide-character API users.

[G. Branden Robinson]

Introduce locution "input character reading function" to abstract
`wgetch()` and `wget_wch()`.  It is admittedly a mouthful.
---
 man/curs_inopts.3x | 78 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 56 insertions(+), 22 deletions(-)

diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x
index fa663edb0..6f8455ded 100644
--- a/man/curs_inopts.3x
+++ b/man/curs_inopts.3x
@@ -134,12 +134,24 @@ .SS "cbreak, nocbreak"
 .I curses
 set the \fB\%cbreak\fP mode.
 Note that \fB\%cbreak\fP overrides \fBraw\fP.
-[See \fB\%wgetch\fP(3X) for a discussion of how these routines
-interact with \fBecho\fP and \fB\%noecho\fP.]
+\fB\%wgetch\fP(3X)
+(wide-character API users:
+\fB\%wget_wch\fP(3X))
+discusses how
+.B \%cbreak
+and
+.B \%nocbreak
+interact with
+.B echo
+and
+.BR \%noecho "."
 .\"
 .SS "echo, noecho"
 The \fBecho\fP and \fB\%noecho\fP routines control whether characters
-typed by the user are echoed by \fB\%wgetch\fP(3X) as they are typed.
+typed by the user are echoed by \fB\%wgetch\fP(3X)
+(wide-character API users:
+\fB\%wget_wch\fP(3X))
+as they are typed.
 Echoing by the terminal driver is always disabled,
 but initially \fB\%wgetch\fP is in echo mode,
 so characters typed are echoed.
@@ -147,9 +159,17 @@ .SS "echo, noecho"
 their own echoing in a controlled area of the screen,
 or not to echo at all,
 so they disable echoing by calling \fB\%noecho\fP.
-[See \fB\%wgetch\fP(3X) for a
-discussion of how these routines interact with \fB\%cbreak\fP and
-\fB\%nocbreak\fP.]
+\fB\%wgetch\fP(3X)
+(wide-character API users:
+\fB\%wget_wch\fP(3X))
+discusses how
+.B echo
+and
+.B \%noecho
+interact with
+.B \%cbreak
+and
+.BR \%nocbreak "."
 .\"
 .SS halfdelay
 The \fB\%halfdelay\fP routine is used for half-delay mode,
@@ -189,9 +209,16 @@ .SS keypad
 .BR TRUE ),
 the user can press a function key
 (such as an arrow key)
-and \fB\%wgetch\fP(3X) returns a single value representing the function
-key,
+and the input character reading function \fB\%wgetch\fP(3X)
+returns a value representing the function key,
 as in \fB\%KEY_LEFT\fP.
+(Wide-character API users:
+\fB\%wget_wch\fP(3X)
+returns
+.B \%KEY_CODE_YES
+to indicate the availability of a function key code in its
+.I wch
+parameter.)
 If disabled
 (\fIbf\fP is \fBFALSE\fP),
 .I curses
@@ -237,23 +264,28 @@ .SS "nl, nonl"
 display device translates the return key into newline on input.
 .\"
 .SS nodelay
-The \fB\%nodelay\fP option causes \fB\%wgetch\fP to be a non-blocking
-call.
+.B \%nodelay\fP
+configures the input character reading function \fB\%wgetch\fP(3X)
+(wide-character API users:
+\fB\%wget_wch\fP(3X))
+to be non-blocking for window
+.IR "win" .
 If no input is ready,
-\fB\%wgetch\fP returns \fBERR\fP.
+the reading function returns
+.BR ERR "."
 If disabled
 .RI ( bf
 is
 .BR FALSE ),
-\fB\%wgetch\fP waits until a key is pressed.
+the reading function does not return until it has input.
 .SS notimeout
-When interpreting an escape sequence,
-\fB\%wgetch\fP(3X) sets a timer
-while waiting for the next character.
-If
+When the input character reading function \fB\%wgetch\fP(3X)
+(wide-character API users:
+\fB\%wget_wch\fP(3X))
+reads an ESC character,
+it sets a timer while waiting for the next character.
 \fB\%notimeout(\fIwin\fR, \fBTRUE\fP)
-is called,
-then \fB\%wgetch\fP does not set a timer.
+disables this timer.
 The purpose of the timeout is to distinguish sequences produced by a
 function key from those typed by a user.
 .\"
@@ -528,10 +560,12 @@ .SH PORTABILITY
 .PP
 Low-level applications can use \fB\%tigetstr\fP to obtain the definition
 of any particular string capability.
-Higher-level applications which use the
-.I curses
-\fB\%wgetch\fP and similar functions to return keycodes rely upon the
-order in which the strings are loaded.
+Higher-level
+applications use the input character reading function \fB\%wgetch\fP(3X)
+(wide-character API users:
+\fB\%wget_wch\fP(3X))
+to obtain key codes from input and rely upon the order in which the
+string capabilities are loaded.
 If more than one key definition has the same string value,
 then \fB\%wgetch\fP can return only one keycode.
 Most
-- 
2.30.2

signature.asc
Description: PGP signature