[PATCH 19/19] Explain opacity as it applies to ncurses programming.

[G. Branden Robinson]

* INSTALL:
* README:
* man/curs_opaque.3x: Do it.
---
 INSTALL            | 7 ++++---
 README             | 2 +-
 man/curs_opaque.3x | 8 ++++++++
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/INSTALL b/INSTALL
index d6ebad29..aa13a707 100644
--- a/INSTALL
+++ b/INSTALL
@@ -670,9 +670,10 @@ CONFIGURE OPTIONS:
     --enable-opaque-form
     --enable-opaque-menu
     --enable-opaque-panel
-       Define symbol in curses.h which controls whether some library
-       structures are treated as "opaque".  The --enable-opaque-curses option
-       may be overridden by the --enable-reentrant option.
+       Define symbol in curses.h controlling whether some library structures
+       are opaque, meaning that their members are accessible only via the
+       documented API.  The --enable-opaque-curses option may be overridden
+       by the --enable-reentrant option.
 
        Enabling opaque-curses enables opaque for the form, menu, and panel
        libraries.  Use their corresponding options to disable the feature
diff --git a/README b/README
index 8524958b..bdfadc60 100644
--- a/README
+++ b/README
@@ -82,7 +82,7 @@ version.
 
 If you configure using the --enable-reentrant option, a "t" is appended to the
 library names (e.g., libncursest.a) and the resulting libraries have a
-different binary interface which makes the ncurses interface more "opaque".
+different binary interface, making the ncurses interface more opaque.
 
 The ncurses libraries implement the curses API.  The panel, menu and forms
 libraries implement clones of the SVr4 panel, menu and forms APIs.  The source
diff --git a/man/curs_opaque.3x b/man/curs_opaque.3x
index a4fb1572..bda79128 100644
--- a/man/curs_opaque.3x
+++ b/man/curs_opaque.3x
@@ -82,6 +82,14 @@ .SH DESCRIPTION
 \fI\%WINDOW\fP structure,
 allowing it to be \*(``opaque\*('' if
 the application defines the \fB\%NCURSES_OPAQUE\fP preprocessor symbol.
+\fIOpacity\fP in this sense means that the members of \fIstruct\fP data
+types are not directly accessible
+(for instance,
+through \*(``.\*('' or \*(``\->\*('' operators),
+but instead must be queried and/or set via library functions.
+Advantages of opacity include greater abstraction and improved
+management of concurrent accesses to data structures,
+keeping object states coherent.
 .TP
 \fBis_cleared\fP
 returns the value set by \fB\%clearok\fP(3X).
-- 
2.30.2

signature.asc
Description: PGP signature