[PATCH 15/42] man/ncurses.3x: Revise.

[G. Branden Robinson]

Content:
* Retitle "Datatypes" subsection to "Overview"; documenting ncurses's
  data types is mostly delegated to curs_variables.3x.
* Define terms and concepts before using them.
* Heavily recast this subsection to introduce the library's basic
  abstractions.
* Explain what *curses means by "optimization" and why it peforms it.
* Motivate existence of terminfo API.
* Clarify that the spelling of `mvw` functions does not predict the
  ordering of their parameters.
* Clarify that "setting" the `NCURSES_NO_HARD_TABS` and
  `NCURSES_NO_MAGIC_COOKIE` environment variables implies nothing about
  their values.
* Stop talking about CRT technology as if it were typical of
  human/computer interaction in the present.  Time marches on...
* Revise discussion of character cell attributes and cross reference an
  appropriate man page.
* Revise discussion of key input interpretation and cross reference an
  appropriate man page.
* Recast discussion of the wide library configuration.
* Add internal (sub)section cross references where fortuitous.
* Migrate terminology: change "normal" (cf. "wide") to "non-wide"
  because (1) "normal" is also the term used to distinguish one
  configuration of the library from "shared", "debug", and "profile"
  configurations, a decision orthogonal to choice of the character-width
  API; and (2) a future default ncurses API might be wide, making it
  "normal" in this mundane sense.
* Add more examples of wide configuration function names.
* Refer to "X/Open Curses", not "XPG4", which turns 30 years old soon.

Style:
* Apply more consistent text styling conventions.
  + Set "curses", function parameter names, and data type names in
    italics.
* Fix grammar nits, particularly those involving relative pronouns and
  restrictive vs.  non-restrictive clauses.
* Protect data type, function, and variable names from hyphenation.
* Drop relative inset around library configurations.
* Tune tag widths so that they set more pleasantly.

Markup:
* Use empty request between chunks of raw *roff prologue that serve
  different purposes.
* Migrate from font selection escape sequences `\f` to man(7) font style
  macros where this won't interfere with sed-driven rewrites of man page
  cross references.  I'm not doing this rigorously.  (Yet?)
---
 man/ncurses.3x | 363 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 249 insertions(+), 114 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 03b149765..5e0c60eca 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -40,6 +40,7 @@
 .ie t .ds '' ''
 .el   .ds '' ""
 .\}
+.
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
@@ -159,55 +160,132 @@ .SS Initialization
 after the shell environment variable \fITERM\fP has been exported.
 (The BSD-style \fB\%@TSET@\fP(1) utility also performs this function.)
 See subsection \*(``Tabs and Initialization\*('' of \fBterminfo\fP(5).
-.SS Datatypes
-The \fI\%ncurses\fP library permits manipulation of data structures,
-called \fIwindows\fP, which can be thought of as two-dimensional
-arrays of characters representing all or part of a CRT screen.
-A default window called \fBstdscr\fP, which is the size of the terminal
-screen, is supplied.
-Others may be created with \fBnewwin\fP.
-.PP
-Note that \fBcurses\fP does not handle overlapping windows, that's done by
-the \fBpanel\fP(3X) library.
-This means that you can either use
-\fBstdscr\fP or divide the screen into tiled windows and not using
-\fBstdscr\fP at all.
-Mixing the two will result in unpredictable, and undesired, effects.
-.PP
-Windows are referred to by variables declared as \fBWINDOW *\fP.
-These data structures are manipulated with routines described here and
-elsewhere in the \fI\%ncurses\fP manual pages.
-Among those, the most basic
-routines are \fBmove\fP and \fBaddch\fP.
-More general versions of
-these routines are included with names beginning with \fBw\fP,
-allowing the user to specify a window.
-The routines not beginning
-with \fBw\fP affect \fBstdscr\fP.
-.PP
-After using routines to manipulate a window, \fBrefresh\fP(3X) is called,
-telling \fBcurses\fP to make the user's CRT screen look like
-\fBstdscr\fP.
-The characters in a window are actually of type
-\fBchtype\fP, (character and attribute data) so that other information
-about the character may also be stored with each character.
+.SS Overview
+A
+.I curses
+library abstracts the terminal screen by representing all or part of it
+as a
+.I \%WINDOW
+data structure.
+A
+.I window
+is a rectangular grid of character cells,
+addressed by row and column coordinates
+.RI ( y ,
+.IR x ),
+with the upper left corner as (0, 0).
+A window called \fB\%stdscr\fP,
+the same size as the terminal screen,
+is always available.
+Create others with \fB\%newwin\fP(3X).
+.PP
+A
+.I curses
+library does not manage overlapping windows.
+(See \fBpanel\fP(3X) if you desire this.)
+You can either use \fB\%stdscr\fP to manage one screen-filling window,
+or tile the screen into non-overlapping windows and not use
+\fB\%stdscr\fP at all.
+Mixing the two approaches will result in unpredictable,
+and undesired,
+effects.
+.PP
+Functions permit manipulation of a window and the
+.I cursor
+identifying the cell within it at which the next output operation will
+occur.
+Among those,
+the most basic are \fBmove\fP(3X) and \fB\%addch\fP(3X):
+these place the cursor and write a character to
+.BR \%stdscr ,
+respectively.
+As a rule,
+window-addressing functions feature names prefixed
+(or infixed,
+see below)
+with \*(``w\*('';
+these allow the user to specify a pointer to a
+.I \%WINDOW.
+Counterparts not thus prefixed
+(or infixed)
+affect \fB\%stdscr\fP.
+Because moving the cursor prior to another operation is so common,
+.I curses
+generally also provides functions with a \*(``mv\*('' prefix as a
+convenience.
+Thus,
+the library defines all of
+\fB\%addch\fP,
+\fB\%waddch\fP,
+\fB\%mvaddch\fP,
+and
+\fB\%mvwaddch\fP.
+When both prefixes are present,
+the order of arguments is a
+.I \%WINDOW
+pointer first,
+then a
+.I y
+and
+.I x
+coordinate pair.
+.PP
+Updating the terminal screen with every
+.I curses
+call can cause unpleasant flicker or inefficient use of the
+communications channel to the device.
+Therefore,
+after using
+.I curses
+functions to accumulate a set of desired updates that make sense to
+present together,
+call \fB\%refresh\fP(3X) to tell the library to make the user's screen
+look like \fBstdscr\fP.
+.I \%ncurses
+.\" X/Open Curses Issue 7 assumes some optimization will be done, but
+.\" does not mandate it in any way.
+.I optimizes
+its output by computing a minimal number of operations to mutate the
+screen from its state at the previous refresh to the new one.
+Effective optimization demands accurate information about the terminal
+device:
+the management of such information is the province of the
+\fB\%terminfo\fP(3X) API,
+a feature of every standard
+.I curses
+implementation.
 .PP
 Special windows called \fIpads\fP may also be manipulated.
-These are windows
-which are not constrained to the size of the screen and whose contents need not
-be completely displayed.
-See \fBcurs_pad\fP(3X) for more information.
-.PP
-In addition to drawing characters on the screen, video attributes and colors
-may be supported, causing the characters to show up in such modes as
-underlined, in reverse video, or in color on terminals that support such
-display enhancements.
-Line drawing characters may be specified to be output.
-On input, \fBcurses\fP is also able to translate arrow and function keys that
-transmit escape sequences into single values.
-The video attributes, line
-drawing characters, and input values use names, defined in \fB<curses.h>\fP,
-such as \fBA_REVERSE\fP, \fBACS_HLINE\fP, and \fBKEY_LEFT\fP.
+These are windows that are not constrained to the size of the terminal
+screen and whose contents need not be completely displayed.
+See \fB\%curs_pad\fP(3X).
+.PP
+In addition to drawing characters on the screen,
+rendering attributes and colors may be supported,
+causing the characters to show up in such modes as underlined,
+in reverse video,
+or in color on terminals that support such display enhancements.
+See \fB\%curs_attr\fP(3X).
+.PP
+.I curses
+is implemented using the operating system's terminal driver;
+keystroke events are not received as scan codes but as byte sequences.
+Graphical keycaps
+(alphanumeric and punctuation keys,
+and the space)
+appear as-is.
+Everything else,
+including the tab,
+enter/return,
+keypad,
+arrow,
+and function keys,
+appears as a control character or a multibyte
+.I "escape sequence."
+.I curses
+translates these into unique
+.I "key codes."
+See \fB\%getch\fP(3X).
 .SS Environment variables
 If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set,
 or if the
@@ -293,53 +371,88 @@ .SS Routine and Argument Names
 are defined in \fB<curses.h>\fP.
 Types used for the terminfo routines such as
 \fBTERMINAL\fP are defined in \fB<term.h>\fP.
-.PP
-This manual page describes functions which may appear in any configuration
+.SS "Wide and Non-wide Character Configurations"
+This manual page describes functions that appear in any configuration
 of the library.
-There are two common configurations of the library:
-.RS 3
-.TP 5
-.I ncurses
-the \*(``normal\*('' library, which handles 8-bit characters.
-The normal (8-bit) library stores characters combined with attributes
-in \fBchtype\fP data.
+There are two common configurations;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
+.TP 10 \" "ncursesw" + 2n
+.I \%ncurses
+is the library in its \*(``non-wide\*('' configuration,
+handling only eight-bit characters.
+It stores a character combined with attributes in a
+.I \%chtype
+datum.
 .IP
-Attributes alone (no corresponding character) may be stored in \fBchtype\fP
-or the equivalent \fBattr_t\fP data.
-In either case, the data is stored in something like an integer.
-.IP
-Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP.
-.TP 5
-.I ncursesw
-the so-called \*(``wide\*('' library, which handles multibyte characters
-(see the section on \fBALTERNATE CONFIGURATIONS\fP).
-The \*(``wide\*('' library includes all of the calls
-from the \*(``normal\*('' library.
-It adds about one third more calls using data types which store
-multibyte characters:
-.RS 5
-.TP 5
-.B cchar_t
-corresponds to \fBchtype\fP.
-However it is a structure, because more data is stored than can fit into
-an integer.
-The characters are large enough to require a full integer value \- and there
-may be more than one character per cell.
-The video attributes and color are stored in separate fields of the structure.
+Attributes alone
+(with no corresponding character)
+can be stored in variables of
+.I \%chtype
+or
+.I \%attr_t
+type.
+In either case,
+they are represented as an integral bit mask.
 .IP
-Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP.
+Each cell of a
+.I \%WINDOW
+is stored as a
+.I \%chtype.
+.TP 10
+.I \%ncursesw
+is the library in its \*(``wide\*('' configuration,
+which handles character encodings requiring a larger data type than
+.I \%char
+(a byte-sized type)
+can represent.
+It adds about one third more calls using additional data types that
+can store such
+.I multibyte
+characters.
+.RS 10 \" same as foregoing tag width
+.TP 9 \" "cchar_t" + 2n
+.I \%cchar_t
+corresponds to the non-wide configuration's
+.I \%chtype.
+It always a structure type,
+because it stores more data than can fit into an integer.
+A character code may be larger than can fit in a C
+.I \%char,
+and moreover more than one character may occupy a cell
+(as with accent marks and other diacritics).
+Each character is of type
+.I \%wchar_t;
+a complex character contains one spacing character and zero or more
+non-spacing characters
+(see below).
+Attributes and color data are stored in separate fields of the
+structure,
+not combined as in
+.I \%chtype.
 .IP
-The \fBsetcchar\fP(3X) and \fBgetcchar\fP(3X)
-functions store and retrieve the data from
-a \fBcchar_t\fP structure.
-.TP 5
-.B wchar_t
-stores a \*(``wide\*('' character.
-Like \fBchtype\fP, this may be an integer.
+Each cell
+(row and column)
+.I \%WINDOW
+is stored as a
+.I \%cchar_t.
+.PP
+The \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
+functions store and retrieve the data from a
+.I \%cchar_t
+structure.
+The wide library API of
+.I \%ncurses
+depends on two data types standardized by ISO C95.
+.TP 9
+.I \%wchar_t
+stores a wide character.
+Like
+.I \%chtype,
+this may be an integer.
 Depending on the character encoding,
 a wide character may be
 .I spacing,
-meaning that it can occupy a character cell by itself and typically
+meaning that it occupies a character cell by itself and typically
 accompanies cursor advancement on input,
 or
 .I combining,
@@ -347,25 +460,44 @@ .SS Routine and Argument Names
 is often regarded as a \*(``modifier\*('' of the base glyph with which
 it combines,
 and typically does not advance the cursor on input.
-.TP 5
-.B wint_t
-stores a \fBwchar_t\fP or \fBWEOF\fP \- not the same, though both may have
-the same size.
+.TP 9
+.I \%wint_t
+can store a
+.I \%wchar_t
+or the constant
+.BR \%WEOF ,
+analogously to the
+.IR int -sized
+character manipulation functions of ISO C and their constant
+.BR \%EOF .
 .RE
 .IP
-The \*(``wide\*('' library provides new functions which are analogous to
-functions in the \*(``normal\*('' library.
-There is a naming convention which relates many of the normal/wide variants:
-a \*(``_w\*('' is inserted into the name.
-For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
-.RE
+The wide library provides additional functions that complement those in
+the non-wide library where the size of the underlying character type is
+significant.
+A somewhat regular naming convention relates many of the wide variants
+to their non-wide counterparts;
+where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
+prefix it with \*(``_w\*('' to obtain the wide counterpart.
+For example,
+\fB\%waddch\fP becomes \fB\%wadd_wch\fP.
+.IP
+This convention is inapplicable to some non-wide function names,
+so other transformations are used for the wide configuration:
+in the window background management functions,
+\*(``bkgd\*('' becomes \*(``bkgrnd\*('';
+the window border-drawing and -clearing functions are suffixed with
+\*(``_set\*(''.
 .\"
 .SS Routine Name Index
-The following table lists the \fBcurses\fP routines provided in
-the \*(``normal\*('' and \*(``wide\*('' libraries and the names of
-the manual pages on which they are described.
-Routines flagged with \*(``*\*(''
-are \fI\%ncurses\fP-specific, not described by XPG4 or present in SVr4.
+The following table lists the
+.I curses
+functions provided in the non-wide and wide APIs and the names of the
+manual pages on which they are described.
+Those flagged with \*(``*\*(''
+are
+.IR \%ncurses -specific,
+neither described by X/Open Curses nor present in SVr4.
 .PP
 .TS
 center tab(/);
@@ -856,11 +988,15 @@ .SH RETURN VALUE
 \fBgetmaxyx\fP are undefined (i.e., these should not be used as the
 right-hand side of assignment statements).
 .PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions with a \*(``mv\*('' prefix first perform cursor movement using
+\fB\%wmove\fP and return an error if the position is outside the window,
+or
+(for \*(``mvw\*('' functions)
+if the
+.I \%WINDOW
+pointer is null.
 Most \*(``mv\*(''-prefixed functions
-(except variadic functions such as \fBmvprintw\fP)
+(except variadic functions such as \fB\%mvprintw\fP)
 are provided both as macros and functions.
 .PP
 Routines that return pointers return \fBNULL\fP on error.
@@ -1005,17 +1141,16 @@ .SS \fINCURSES_GPM_TERMS\fP
 \fI\%ncurses\fP will attempt to open GPM if \fITERM\fP contains
 \*(``linux\*(''.
 .SS \fINCURSES_NO_HARD_TABS\fP
-\fI\%ncurses\fP may use tabs as part of the cursor movement
-optimization.
+\fI\%ncurses\fP may use tabs as part of cursor movement optimization.
 In some cases,
 your terminal driver may not handle these properly.
-Set this environment variable to disable the feature.
+Set this environment variable to any value to disable the feature.
 You can also adjust your \fBstty\fP(1) settings to avoid the problem.
 .SS \fINCURSES_NO_MAGIC_COOKIE\fP
 Some terminals use a magic-cookie feature which requires special handling
 to make highlighting and other video attributes display properly.
 You can suppress the highlighting entirely for these terminals by
-setting this environment variable.
+setting this environment variable to any value.
 .SS \fINCURSES_NO_PADDING\fP
 Most of the terminal descriptions in the terminfo database are written
 for real \*(``hardware\*('' terminals.
@@ -1353,10 +1488,10 @@ .SH ALTERNATE CONFIGURATIONS
 may require a specific value for \fB_XOPEN_SOURCE\fP
 (or a system-specific symbol).
 .PP
-The \fBcurses.h\fP file which is installed for the wide-character
-library is designed to be compatible with the normal library's header.
-Only the size of the \fBWINDOW\fP structure differs, and very few
-applications require more than a pointer to \fBWINDOW\fPs.
+The \fI\%curses.h\fP header file installed for the wide-character
+library is designed to be compatible with the non-wide library's header.
+Only the size of the \fI\%WINDOW\fP structure differs;
+few applications require more than pointers to \fI\%WINDOW\fPs.
 .PP
 If the headers are installed allowing overwrite,
 the wide-character library's headers should be installed last,
-- 
2.30.2

signature.asc
Description: PGP signature