[PATCH 13/45] man/curs_inopts.3x: Revise discussion of intrflush, {no,}qiflush.

[G. Branden Robinson]

* Add discussion of these functions to "HISTORY" section.
* Recast `intrflush()` description as redirection to `{no,}qiflush()`.
* Recast `{no,}qiflush()` description for clarity.
* Mention potential downside of `noqiflush()`.
* Mention `typeahead()` as mitigation of `noqiflush()`'s downside.
---
 man/curs_inopts.3x | 94 +++++++++++++++++++++++++++++++---------------
 1 file changed, 64 insertions(+), 30 deletions(-)

diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x
index 74a1a7758..03a410942 100644
--- a/man/curs_inopts.3x
+++ b/man/curs_inopts.3x
@@ -162,29 +162,23 @@ .SS halfdelay
 Use \fB\%nocbreak\fP to leave half-delay mode.
 .\"
 .SS intrflush
-If the \fB\%intrflush\fP option is enabled
-.RI ( bf
+.B \%intrflush
+calls
+.B \%qiflush
+(see below)
+if
+.I bf
 is
-.BR TRUE ),
-and an interrupt key is pressed on the keyboard
-(interrupt,
-break,
-quit),
-all output in the terminal driver queue is flushed,
-giving the effect of faster response to the interrupt,
-but causing
-.I curses
-to have the wrong idea of what is on the screen.
-Disabling the option
-.RI ( bf
+.BR TRUE ","
+and
+.B \%noqiflush
+if
+.I bf
 is
-.BR FALSE ),
-prevents the flush.
-The default for the option is inherited from the terminal driver
-settings.
-The
+.BR FALSE "."
+It ignores its
 .I win
-argument is ignored.
+argument.
 .\"
 .SS keypad
 The \fB\%keypad\fP option enables the keypad of the user's terminal.
@@ -281,16 +275,45 @@ .SS "raw, noraw"
 .IR curses .
 .\"
 .SS "qiflush, noqiflush"
-When the \fB\%noqiflush\fP routine is used,
-normal flush of input and output queues associated with the \fBINTR\fP,
-\fBQUIT\fP and \fBSUSP\fP characters will not be done
-[see \fB\%termios\fP(3)].
-When
-\fB\%qiflush\fP is called,
-the queues will be flushed when these control characters are read.
-You may want to call \fB\%noqiflush\fP in a signal handler if you want
-output to continue as though the interrupt had not occurred,
-after the handler exits.
+.\"
+.B \%qiflush
+and
+.B \%noqiflush
+configure the terminal driver's treatment of its input and output queues
+when it handles the
+.IR interrupt ","
+.IR suspend ","
+or
+.I quit
+characters in
+.I \%cbreak
+and \*(``cooked\*('' modes;
+on POSIX systems,
+see \fI\%termios\fP(3).
+The default behavior is inherited from the terminal driver settings.
+Calling
+.B \%qiflush
+configures the terminal to flush the queues when any of these events
+occurs,
+giving the impression of faster response to user input,
+but causes
+.I curses
+to have the wrong idea of what is on the screen.
+Calling
+.B \%noqiflush
+prevents such flushing,
+but might frustrate impatient users on slow connections if a
+.I curses
+update of the screen is in progress when the event occurs;
+see
+.B \%typeahead
+below for a mitigation of this problem.
+You may want to call
+.B \%noqiflush
+in a signal handler
+if you want output to continue
+after the handler exits
+as though the interrupt had not occurred.
 .\"
 .SS "timeout, wtimeout"
 The \fB\%timeout\fP and \fB\%wtimeout\fP routines set blocking or
@@ -527,6 +550,17 @@ .SH PORTABILITY
 key definition,
 the later definition is the one used.
 .SH HISTORY
+SVr2 (1984) introduced
+.IR \%intrflush "."
+.I \%qiflush
+and
+.I \%noqiflush
+appeared in SVr3.1 (1987),
+at which point
+.I \%intrflush
+became a wrapper for either of these functions,
+depending on the value of its Boolean argument.
+.PP
 Formerly,
 .I \%ncurses
 used
-- 
2.30.2

signature.asc
Description: PGP signature