[PATCH 1/3] man/curs_variables.3x: Revise.

[G. Branden Robinson]

* Document data types and constants: bool, chtype, cchar_t, attr_t,
  WINDOW, TRUE, FALSE, ERR, OK.  Elide underlying type information.

* Drop definition of page-local macro `bP` (see below).
* Define `:` string to interpolate the groff `\:` extension escape
  sequence if available (it marks break points that should not be
  hyphenated), and nothing otherwise.
* Set C comments in italics but ellipses in roman.
* Drop unnecessary `br` requests; filling is already disabled in the
  "SYNOPSIS" section.
* Set "curses", "ncurses", and "terminfo" in italics, not bold.
* Protect literals from hyphenation.
* When discussing ncurses, use its name, instead of implying it or
  saying "this implementation" elliptically.
* Recast to fix numerous grammar goofs.
  - "this variable" doesn't "initializ[e] curses".
  - Establish unambiguous antecedents for pronouns.
  - Say "consequently", implying reaction or causation, rather than
    "likewise", which implies similarity, analogy, or complementarity.
  - Fix numerical agreement ("units...of a millisecond" [sic]).
* Recast to improve style (subjectively).
  - Favor active voice over passive.
  - Favor present tense over future.
* Set data type names in italics; motivated by the existing italics on
  "signed short", apply it to "bool", "chtype", "cchar_t", "attr_t", and
  "WINDOW".
* Use a real multiplication sign in prose.  English is not C; this fact
  is a source of pride for many C programmers who disparage Ada.
* Migrate from `bP` page-local macro `IP` man(7) macro.  Use 2 ens of
  indentation for bulleted lists.
* Clarify motivation of `ESCDELAY` feature.
* Retitle subsections from "The {Current,New,Standard} Screen" to the
  names of the ncurses objects that instantiate them, for greater
  consistency with the existing subsection headings.
* Just because ncurses doesn't enforce a limit on ESCDELAY doesn't mean
  the language (or machine) won't.
* Add cross reference to UAX #29 document so that the reader might
  understand grapheme clusters and the usage of the cchar_t type.  Set
  URL using `:` string so that it doesn't break grodily.
* Break long input lines.
---
 man/curs_variables.3x | 287 ++++++++++++++++++++++++++++--------------
 1 file changed, 190 insertions(+), 97 deletions(-)

diff --git a/man/curs_variables.3x b/man/curs_variables.3x
index dfe81ac4..2bb82695 100644
--- a/man/curs_variables.3x
+++ b/man/curs_variables.3x
@@ -33,12 +33,19 @@
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
-.de bP
-.ie n  .IP \(bu 4
-.el    .IP \(bu 2
-..
+.ie \n(.g .ds : \:
+.el       .ds : \" empty
 .ds n 5
 .SH NAME
+\fI\%bool\fP,
+\fI\%chtype\fP,
+\fI\%cchar_t\fP,
+\fI\%attr_t\fP,
+\fI\%WINDOW\fP,
+\fB\%TRUE\fP,
+\fB\%FALSE\fP,
+\fB\%ERR\fP,
+\fB\%OK\fP,
 \fB\%COLORS\fP,
 \fB\%COLOR_PAIRS\fP,
 \fB\%COLS\fP,
@@ -48,133 +55,215 @@ .SH NAME
 \fB\%curscr\fP,
 \fB\%newscr\fP,
 \fB\%stdscr\fP \-
-\fIcurses\fR global variables
+\fIcurses\fR data types,
+constants,
+and global variables
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>\fP
 .PP
+\fI/* data types */\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW;\fP
+.PP
+\fI/* constants */\fP
+\fBconst bool TRUE;\fP
+\fBconst bool FALSE;\fP
+.PP
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR;\fP
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP OK;\fP
+.PP
+\fI/* variables */\fP
 \fBint COLOR_PAIRS;\fP
-.br
 \fBint COLORS;\fP
-.br
 \fBint COLS;\fP
-.br
 \fBint ESCDELAY;\fP
-.br
 \fBint LINES;\fP
-.br
 \fBint TABSIZE;\fP
-.br
 \fBWINDOW * curscr;\fP
-.br
 \fBWINDOW * newscr;\fP
-.br
 \fBWINDOW * stdscr;\fP
 .fi
 .SH DESCRIPTION
-This page summarizes variables provided by the \fBcurses\fP library.
-A more complete description is given in the \fBcurses\fP(3X) manual page.
+This page summarizes data types,
+constants,
+and variables provided by the \fIcurses\fP library.
+Locate further discussion in \fB\%curses\fP(3X).
 .PP
-Depending on the configuration, these may be actual variables,
-or macros (see \fBcurs_threads\fP(3X) and \fBcurs_opaque\fP(3X))
-which provide read-only access to \fIcurses\fP's state.
-In either case, applications should treat them as read-only to avoid
+Depending on \fIncurses\fP's build-time configuration,
+the variables may instead be
+macros (see \fB\%curs_threads\fP(3X) and \fB\%curs_opaque\fP(3X))
+that provide read-only access to the library's state.
+In either case,
+applications should treat them as read-only to avoid
 confusing the library.
+.SS bool, TRUE, FALSE
+X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98
+standards,
+each of which also defined a Boolean data type.
+The \fIcurses\fP library requires an integral type \fIbool\fP and
+constants \fBTRUE\fP and \fBFALSE\fP to store its two possible values.
+.SS ERR, OK
+\fIcurses\fP and \fIterminfo\fP routines frequently return these
+constant integral values indicating failure and success,
+respectively.
+.SS chtype
+The \fI\%chtype\fP integral type combines a
+(\*(``narrow\*('',
+8-bit)
+character with attributes encoding the character's \fIrendition\fP,
+such as the styling of its typeface and/or foreground and background
+colors.
+See,
+for example,
+\fB\%addch\fP(3X),
+\fB\%attron\fP(3X),
+and
+\fB\%inch\fP(3X).
+.SS cchar_t, attr_t
+\fI\%chtype\fP is too small for the standard C library's wide-character
+type,
+\fIwchar_t\fP.
+\fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
+enough wide characters to store what Unicode terms a \fIgrapheme
+cluster\fP
+(a \*(``user-perceived character\*('' [UAX #29],
+which may nevertheless require several character encoding units to
+represent).
+\fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
+apply to \fI\%cchar_t\fPs.
+See,
+for example,
+\fB\%add_wch\fP(3X),
+\fB\%attr_on\fP(3X),
+and
+\fB\%in_wch\fP(3X).
 .SS COLOR_PAIRS
-After initializing curses, this variable contains the number of color pairs
-which the terminal can support.
-Usually the number of color pairs will be the product 
\fBCOLORS\fP*\fBCOLORS\fP,
-however this is not always true:
-.bP
-a few terminals use HLS colors, which do not follow this rule
-.bP
+Once \fIcurses\fP is initialized,
+\fB\%COLOR_PAIRS\fP
+contains the number of color pairs supported by the terminal.
+Often,
+its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
+but this is not always true.
+.IP \(bu 2
+A few terminals use HLS colors,
+ignoring this rule;
+and
+.IP \(bu
 terminals supporting a large number of colors are limited by the number
-of color pairs that can be represented in a \fIsigned short\fP value.
+of color pairs that a \fIsigned short\fP value can represent.
 .SS COLORS
-After initializing curses, this variable contains the number of colors
-which the terminal can support.
+Once \fIcurses\fP is initialized,
+\fB\%COLORS\fP
+contains the number of colors supported by the terminal.
 .SS COLS
-After initializing curses, this variable contains the width of the screen,
-i.e., the number of columns.
+Once \fIcurses\fP is initialized,
+\fB\%COLS\fP
+contains the screen's width in character cells;
+that is,
+the number of columns.
 .SS ESCDELAY
-This variable holds the number of milliseconds to wait after reading an
-escape character,
-to distinguish between an individual escape character entered on the
-keyboard from escape sequences sent by cursor- and function-keys
-(see curses(3X)).
+For \fIcurses\fP to distinguish an escape character corresponding to a
+user's press of an \*(``Escape\*('' key on the input device from one
+included in a control sequence used by a cursor movement or function
+key,
+the library waits to see if another key event occurs after the escape
+character.
+\fB\%ESCDELAY\fP
+stores this interval in milliseconds.
 .SS LINES
-After initializing curses, this variable contains the height of the screen,
-i.e., the number of lines.
+Once \fIcurses\fP is initialized,
+\fB\%LINES\fP
+contains the screen's height in character cells;
+that is,
+the number of lines.
 .SS TABSIZE
-This variable holds the number of columns used by the \fIcurses\fP library
-when converting a tab character to spaces as it adds the tab to a window
-(see \fBcurs_addch\fP(3X).
-.SS The Current Screen
-This implementation of curses uses a special window \fBcurscr\fP to
-record its updates to the terminal screen.
+The \fIcurses\fP library converts a tab character to this number of
+spaces as it adds a tab to a window;
+see \fB\%curs_addch\fP(3X).
+.SS curscr
+\fIncurses\fP records updates to the terminal screen in a \fI\%WINDOW\fP
+structure named \fB\%curscr\fP.
 .PP
-This is referred to as the \*(``physical screen\*('' in the
-\fBcurs_refresh\fP(3X) and
-\fBcurs_outopts\fP(3X) manual pages.
-.SS The New Screen
-This implementation of curses uses a special window \fBnewscr\fP to
-hold updates to the terminal screen before applying them to \fBcurscr\fP.
+This object is referred to as the \*(``physical screen\*('' in
+\fB\%curs_refresh\fP(3X) and
+\fB\%curs_outopts\fP(3X).
+.SS newscr
+\fIncurses\fP collects pending updates to the terminal screen in a
+\fI\%WINDOW\fP structure named \fB\%newscr\fP.
 .PP
-This is referred to as the \*(``virtual screen\*('' in the
-\fBcurs_kernel\fP(3X),
-\fBcurs_refresh\fP(3X) and
-\fBcurs_outopts\fP(3X) manual pages.
-.SS The Standard Screen
-Upon initializing curses,
-a default window called \fBstdscr\fP,
-which is the size of the terminal screen, is created.
-Many curses functions use this window.
+This object is referred to as the \*(``virtual screen\*('' in the
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_refresh\fP(3X),
+and
+\fB\%curs_outopts\fP(3X).
+When the screen is refreshed,
+\fIcurses\fP determines a minimal set of updates using the terminal's
+capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
+.SS stdscr
+Once \fIcurses\fP is initialized,
+it creates a \fI\%WINDOW\fP structure named \fB\%stdscr\fP.
+It is the same size as the terminal screen and is the default window
+used by routines that do not take a parameter identifying one.
+Many \fIcurses\fP functions use this window.
 .SH NOTES
-The curses library is initialized using either \fBinitscr\fP(3X),
-or \fBnewterm\fP(3X).
+Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes
+\fIcurses\fP.
 .PP
-If \fBcurses\fP is configured to use separate curses/terminfo libraries,
-most of these variables reside in the curses library.
+If \fIncurses\fP is configured to provide separate \fIcurses\fP and
+\fIterminfo\fP libraries,
+most of these variables reside in the \fIcurses\fP library.
 .SH PORTABILITY
-\fBTABSIZE\fP is a feature of SVr4 curses
-which is not documented by X/Open curses.
-.bP
-In SVr4 curses, \fBTABSIZE\fP is initially set from the terminal description's
-\fBinit_tabs\fP capability.
-After that, it can be altered by the applications using SVr4 curses.
-.IP
-SVr4 curses uses the current value of \fBTABSIZE\fP to
-compute the position of tabstops for updating both
-the virtual screen with \fBaddch\fP(3X) as well as
-the physical screen with \fBmvcur\fP(3X).
-.bP
-This implementation uses the current value of \fBTABSIZE\fP only for
-updating the virtual screen.
-It uses the terminal description's \fBit\fP (\fBinit_tabs\fP) capability for
-computing hardware tabs (i.e., tab stops on the physical screen).
-.bP
+The X/Open Curses standard documents neither \fB\%TABSIZE\fP nor
+\fB\%ESCDELAY\fP.
+.PP
+\fB\%TABSIZE\fP is an extension in SVr4 \fIcurses\fP.
+.IP \(bu 2
+SVr4 initially sets \fB\%TABSIZE\fP from the terminal description's
+\fB\%init_tabs\fP capability.
+After that,
+it can be altered by applications using SVr4 \fIcurses\fP.
+.IP \(bu
+SVr4 \fIcurses\fP uses the value of \fB\%TABSIZE\fP to compute the
+position of tab stops when updating both
+the virtual screen with \fB\%addch\fP(3X) and
+the physical screen with \fB\%mvcur\fP(3X).
+.IP \(bu
+\fIncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
+virtual screen.
+It uses the terminal description's \*(``\fBit\fP\*(''
+(\fB\%init_tabs\fP) capability for computing hardware tabs
+(that is,
+tab stops on the physical screen).
+.IP \(bu
 Other implementations differ.
-For instance, NetBSD curses allows \fBTABSIZE\fP to be set through
-an environment variable.
-This implementation does not.
+For instance,
+NetBSD \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an
+environment variable.
+\fIncurses\fP does not.
 .IP
-NetBSD curses does not support hardware tabs;
-it uses the \fBinit_tabs\fP capability and the \fBTABSIZE\fP variable
-only for updating the virtual screen.
+NetBSD \fIcurses\fP does not support hardware tabs;
+it uses the \fB\%init_tabs\fP capability and the \fB\%TABSIZE\fP
+variable only for updating the virtual screen.
 .PP
-\fBESCDELAY\fP is an extension in AIX curses:
-.bP
-In AIX, the units for \fBESCDELAY\fP are \fIfifths\fP of a millisecond.
-.bP
-The default value for AIX's \fBESCDELAY\fP is 0.1 seconds.
-.bP
-AIX also enforces a limit of 10,000 seconds for \fBESCDELAY\fP;
-this implementation currently has no upper limit.
+\fB\%ESCDELAY\fP is an extension in AIX \fIcurses\fP.
+.IP \(bu 2
+In AIX,
+the units for \fB\%ESCDELAY\fP are \fIfifths\fP of milliseconds.
+.IP \(bu
+The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds.
+.IP \(bu
+AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP;
+\fIncurses\fP does not enforce any upper limit.
 .PP
-This implementation has long used \fBESCDELAY\fP with units of milliseconds,
+\fIncurses\fP has long used \fB\%ESCDELAY\fP with units of milliseconds,
 making it impossible to be completely compatible with AIX.
-Likewise, most users have either decided to override the value,
-or rely upon its default value.
+Consequently,
+most users have decided either to override the value,
+or to rely upon its default.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_opaque\fP(3X),
@@ -182,3 +271,7 @@ .SH SEE ALSO
 \fB\%curs_threads\fP(3X),
 \fB\%term_variables\fP(3X),
 \fB\%terminfo\fP(\*n)
+.PP
+[UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
+Segmentation\*('';
+\%<https://\*:unicode\*:.org/\*:reports/\*:tr29/>
-- 
2.30.2

signature.asc
Description: PGP signature