[PATCH 169/177] man/curs_util.3x: Revise "DESCRIPTION" section.

[G. Branden Robinson]

Content:
* Rewrite descriptions of `unctrl()` and `wunctrl()`.  Add the latter to
  the subsection heading; it's not a mere variant of the former (in the
  manner that `mvwaddch()` is to `waddch()`, for instance).

Style:
* Ensure that carets and tildes show up as their Unicode Basic Latin
  code points regardless of *roff output device.

Markup:
* Define `ha` and `ti` strings in document preamble; we need them now.
---
 man/curs_util.3x | 80 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 54 insertions(+), 26 deletions(-)

diff --git a/man/curs_util.3x b/man/curs_util.3x
index 6380ba908..aa5f2eff0 100644
--- a/man/curs_util.3x
+++ b/man/curs_util.3x
@@ -33,12 +33,16 @@
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
+.ds ^  \(ha
+.ds ~  \(ti
 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""
+.ds       ^  ^
+.ds       ~  ~
 .\}
 .
 .de bP
@@ -85,37 +89,61 @@ .SH SYNOPSIS
 \fBint flushinp(void);
 .fi
 .SH DESCRIPTION
-.SS unctrl
-The \fBunctrl\fP routine returns a character string as a printable
-representation of the character \fIch\fP:
-.bP
-Printable characters are displayed as themselves,
-e.g.,
-a one-character string containing the key.
-.bP
-Control characters are displayed in the \fB^\fIX\fR notation.
-.bP
-Printing characters are displayed as is.
+.SS "unctrl, wunctrl"
+.B unctrl
+returns a null-terminated character string printably representing the
+.I curses
+character
+.IR ch ,
+often one that originated in keyboard input;
+see \fBgetch\fP(3X).
+.bP
+Printable characters represent themselves as a one-character string.
+.bP
+Control characters are expressed in
+.BI \*^ X
+notation,
+where
+.I X
+is the printable symbol of the control code's value plus 32
+in the ISO\ 646/\*(``ASCII\*('' character set.
 .bP
 DEL
-(character 127)
-is displayed as \fB^?\fP.
+(character code 127)
+is represented as
+.BR \*^? .
 .bP
-Values above 128 are either meta characters
-(if the screen has not been initialized,
-or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP parameter),
-shown in the \fBM\-\fIX\fR notation,
-or are displayed as themselves.
-In the latter case,
-the values may not be printable;
-this follows the X/Open specification.
+A character code greater than 127 is represented in one of two ways.
+.IP
+If the screen has not been initialized or is in meta mode
+(see \fBmeta\fP(3X)),
+it is expressed in
+.BI M- X
+notation,
+where X
+is the representation of the code's value minus 128,
+as described above.
+.IP
+If the screen is not in meta mode,
+the character code is assumed to represent itself.
+It nevertheless may not be printable;
+this is the case for character codes 128-159 in ISO\ 8859 encodings.
+.IP
+.IR \%ncurses 's
+\fB\%use_legacy_coding\fP(3X)
+function configures
+.BR \%unctrl 's
+handling of these character codes.
 .PP
-The corresponding \fBwunctrl\fP returns a printable representation of
-a complex character \fIwch\fP.
+.B \%wunctrl
+returns a null-terminated wide-character string printably representing
+the
+.I curses
+complex character
+.IR wch .
 .PP
-In both \fBunctrl\fP and \fBwunctrl\fP the attributes
-and color associated
-with the character parameter are ignored.
+Both functions ignore the atributes and color pair selection
+of their argument.
 .SS "keyname, key_name"
 The \fBkeyname\fP routine returns a character string
 corresponding to the key \fIc\fP.
-- 
2.30.2

signature.asc
Description: PGP signature