[PATCH 14/30] man/{curs_inch,ncurses}.3x: Kick some programming advice upstairs.

[G. Branden Robinson]

It's better to tell the economical (lazy) application programmer that
they'll have to abandon their plans to use the old, "simple" non-wide
API early if they want to play with Unicode/UTF-8, in the main ncurses
page, rather than burying this admonition in the page for `inch()` once
they may already be working on implementation details.

Also fix clumsy wording in related discussion of `cchar_t`; storage
per se doesn't "fit", it contains.

Annotate a historical detail explaining some of the naming weirdness in
the wide curses API.
---
 man/curs_inch.3x | 12 ------------
 man/ncurses.3x   | 19 ++++++++++++++++++-
 2 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/man/curs_inch.3x b/man/curs_inch.3x
index fffcff30c..0388d6a3e 100644
--- a/man/curs_inch.3x
+++ b/man/curs_inch.3x
@@ -160,18 +160,6 @@ .SH HISTORY
 .\" the Alpha arrived in 1993.  --GBR
 SVr3.2 (1988)
 added a 6-bit color pair identifier alongside the attributes.
-.PP
-X/Open Curses does not specify the sizes of the character code or
-color pair identifier,
-nor the quantity of attribute bits,
-in
-.IR chtype ";"
-these are implementation-dependent.
-.I \%ncurses
-uses eight bits for the character code.
-An application requiring a wider character type,
-for instance to represent Unicode,
-should use the wide-character counterparts of these functions.
 .SH SEE ALSO
 \fB\%curs_in_wch\fP(3X) describes comparable functions of the
 .I \%ncurses
diff --git a/man/ncurses.3x b/man/ncurses.3x
index 24b5ed912..578dd1005 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -463,6 +463,17 @@ .SS "Wide and Non-wide Character Configurations"
 .I \%WINDOW
 is stored as a
 .IR \%chtype .
+X/Open Curses does not specify the sizes of the character code or
+color pair identifier,
+nor the quantity of attribute bits,
+in
+.IR chtype ";"
+these are implementation-dependent.
+.I \%ncurses
+uses eight bits for the character code.
+An application requiring a wider character type,
+for instance to represent Unicode,
+should use the wide-character API.
 .TP 10
 .I \%ncursesw
 is the library in its \*(``wide\*('' configuration,
@@ -483,6 +494,12 @@ .SS "Wide and Non-wide Character Configurations"
 .BR \%addwstr ,
 .BR \%inwstr ,
 and their variants.)
+.\" This is because they operate on "plain" wide-character strings
+.\" (`wchar_t*`) and not curses complex character strings (`cchar_t*`).
+.\" SVID 4 did specify functions like `addwch()` and `inswch()` that
+.\" operated on `chtype`s assuming that they were wide enough for a
+.\" `wchar_t` plus attribute and color pair bits; X/Open Curses did not
+.\" standardize these.
 .IP
 This convention is inapplicable to some non-wide function names,
 so other transformations are used for the wide configuration:
@@ -498,7 +515,7 @@ .SS "Wide and Non-wide Character Configurations"
 corresponds to the non-wide configuration's
 .IR \%chtype .
 It is a structure type
-because it requires more storage than fits into a standard scalar type.
+because it requires more storage than a standard scalar type offers.
 A character code may not be representable as a
 .IR \%char ,
 and moreover more than one character may occupy a cell
-- 
2.30.2

signature.asc
Description: PGP signature