[PATCH 058/100] man/ncurses.3x: Revise "ENVIRONMENT" section, NCURSES_NO_SETBUF (14/21).

[G. Branden Robinson]

* man/man_db.renames.in: Add `printw()` and `putp()`.
---
 man/man_db.renames.in |  2 ++
 man/ncurses.3x        | 77 ++++++++++++++++++++++++-------------------
 2 files changed, 46 insertions(+), 33 deletions(-)

diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 95ae66695..bed545b90 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -229,6 +229,8 @@ nonl.3x                             nonl.3ncurses
 notimeout.3x                   notimeout.3ncurses
 pnoutrefresh.3x                        pnoutrefresh.3ncurses
 prefresh.3x                    prefresh.3ncurses
+printw.3x                      printw.3ncurses
+putp.3x                        putp.3ncurses
 putwin.3x                      putwin.3ncurses
 raw.3x                         raw.3ncurses
 refresh.3x                     refresh.3ncurses
diff --git a/man/ncurses.3x b/man/ncurses.3x
index 576cc3129..fa84b5198 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1317,40 +1317,51 @@ .SS "\fINCURSES_NO_PADDING\fP"
 .B \%flash_screen
 .RB ( flash ).
 .SS "\fINCURSES_NO_SETBUF\fP"
-This setting is obsolete.
-Before changes
-.RS 3
-.bP
-started with 5.9 patch 20120825
-and
-.bP
-continued
-though 5.9 patch 20130126
-.RE
-.PP
-\fI\%ncurses\fP enabled buffered output during terminal initialization.
-This was done (as in SVr4 curses) for performance reasons.
-For testing purposes, both of \fI\%ncurses\fP and certain applications,
+(Obsolete)
+Prior to internal changes developed in
+.I \%ncurses
+5.9
+(patches 20120825 through 20130126),
+the library used \fI\%setbuf\fP(3) to enable fully buffered output when
+initializing the terminal.
+This was done,
+as in SVr4
+.IR curses ,
+to increase performance.
+For testing purposes,
+both of
+.I \%ncurses
+and of certain applications,
 this feature was made optional.
-Setting the \fI\%NCURSES_NO_SETBUF\fP variable
-disabled output buffering, leaving the output in the original (usually
-line buffered) mode.
-.PP
-In the current implementation,
-\fI\%ncurses\fP performs its own buffering and does not require this
-workaround.
-It does not modify the buffering of the standard output.
-.PP
-The reason for the change was to make the behavior for interrupts and
-other signals more robust.
-One drawback is that certain nonconventional programs would mix
-ordinary \fI\%stdio\fP(3) calls with \fI\%ncurses\fP calls and (usually)
-work.
-This is no longer possible since \fI\%ncurses\fP is not using
-the buffered standard output but its own output (to the same file descriptor).
-As a special case, the low-level calls such as \fBputp\fP still use the
-standard output.
-But high-level curses calls do not.
+Setting this variable disabled output buffering,
+leaving the output stream in the original
+(usually line-buffered)
+mode.
+.PP
+Nowadays,
+.I \%ncurses
+performs its own buffering and does not require this workaround;
+it does not modify the buffering of the standard output stream.
+This approach makes signal handling,
+as for interrupts,
+more robust.
+A drawback is that certain unconventional programs mixed
+\fI\%stdio\fP(3) calls with
+.I \%ncurses
+calls and (usually)
+got the behavior they expected.
+This is no longer the case;
+.I \%ncurses
+does not write to the standard output file descriptor through a
+.IR stdio -buffered
+stream.
+.PP
+As a special case,
+low-level API calls such as \fB\%putp\fP(3X) still use the
+standard output stream.
+High-level
+.I curses
+calls such as \fB\%printw\fP(3X) do not.
 .SS "\fINCURSES_NO_UTF8_ACS\fP"
 During initialization, the \fI\%ncurses\fP library
 checks for special cases where VT100 line-drawing (and the corresponding
-- 
2.30.2

signature.asc
Description: PGP signature