Content: * Lead option description by stating what the option (fundamentally) does. Only then proceed to describe relevant consequences. * Document impact of option on ncurses's "tinfo" library. (It would be useful to document _why_ tinfo's wide-character ABI differs; this description's erstwhile text seems to presume that that wouldn't be necessary--or it predates the advent of "tinfo" altogether.) * Give more specific guidance to application developers selecting a linker option. * Document impact of option on ncurses++, panel, form, and menu libraries. * Favor "ncurses" over "this implementation".
Style:
* Format example linker options inline rather than as displays.
* Replace colon dangling at the end of a sentence with a period. The
subsequent use of bulleted paragraphs makes the structure clear.
* Recast.
Markup:
* Use man(7)'s RS/RE macros to properly align paragraphs produced with
the page-local `bP` macro with the surrounding discussion.
* Annotate some open questions.
---
man/ncurses.3x | 89 +++++++++++++++++++++++++++++++-------------------
1 file changed, 56 insertions(+), 33 deletions(-)
diff --git a/man/ncurses.3x b/man/ncurses.3x
index dfc589aeb..70988ff80 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1798,34 +1798,47 @@ .SH "ALTERNATE CONFIGURATIONS"
.RE
.TP 5
.B \-\-enable\-widec
-The configure script renames the library and
-(if the
-.B \%\-\-disable\-overwrite
-option is used)
-puts the header files in a different subdirectory.
-All of the library names have a \*(``w\*('' appended to them,
-i.e., instead of
-.RS 5
-.PP
-.RS 4
-.EX
-.B \-lncurses
-.EE
-.RE
-.PP
-you link with
-.PP
-.RS 4
-.EX
-.B \-lncursesw
-.EE
-.RE
-.PP
-You must also enable the wide-character features in the header file
-when compiling for the wide-character library
+(default for ABI\ 6+ since 2023-10-21)
+Enable support for wide characters.
+The
+.I \%configure
+script renames the
+.I \%ncurses
+library
+(and the
+.I tinfo
+library,
+if
+.B \%\-\-with\-termlib
+is also specified),
+appending \*(``w\*(''.
+An application desirous of wide-character support then uses
+.B \%\-lncursesw
+(or
+.BR \%\-ltinfow )
+instead of
+.B \%\-lncurses
+(or
+.BR \%\-ltinfo )
+as its linker option.
+The
+.IR ncurses++ ","
+.IR panel ","
+.IR form ","
+and
+.I menu
+libraries are renamed similarly.
+.IP
+An application must also
+define certain C preprocessor symbols
+to enable wide-character features
+in
+.I curses
+header files
to use the extended (wide-character) functions.
-The symbol which enables these features has changed
-since X/Open Curses Issue\ 4:
+The symbol that enables these features has changed
+since X/Open Curses Issue\ 4.
+.RS 5
.bP
Originally,
the wide-character feature required the symbol
@@ -1838,9 +1851,11 @@ .SH "ALTERNATE CONFIGURATIONS"
value of 500.
.bP
As of mid-2018,
-none of the features in this implementation require a
+no
+.I \%ncurses
+feature requires a
.I \%_XOPEN_SOURCE
-feature greater than 600.
+value greater than 600.
However,
X/Open Curses Issue\ 7 (2009) recommends defining it to 700.
.bP
@@ -1852,7 +1867,8 @@ .SH "ALTERNATE CONFIGURATIONS"
may require a specific value for
.I \%_XOPEN_SOURCE
(or a system-specific symbol).
-.PP
+.RE
+.IP
The
.I \%curses.h
header file installed
@@ -1863,12 +1879,19 @@ .SH "ALTERNATE CONFIGURATIONS"
structure differs;
few applications require more than pointers to
.IR \%WINDOW "."
-.PP
-If the headers are installed allowing overwrite,
+.\" XXX: What's different in term.h?
+.IP
+If
+.IR \%ncurses 's
+header files are installed allowing overwrite
+(the default,
+but see
+.B \%\-\-disable\-overwrite
+above),
the wide-character library's headers should be installed last,
+.\" Isn't that the responsibility of ncurses's own makefiles? --GBR
to allow applications to be built using either library
from the same set of headers.
-.RE
.TP 5
.B \-\-with\-pthread
The configure script renames the library.
--
2.30.2
signature.asc
Description: PGP signature
