[PATCH 3/3] man/curs_addch.3x: Revise.

[G. Branden Robinson]

Content:
* Clarify that the "next" tab stop can be on a subsequent line.
* Refer to U+000A as "line feed", not "newline".  ECMA-48 seems like a
  more appropriate context for the discussion, since the discussion is
  below the level at which programming environments abstract newlines.
* Rename "Line Drawing" subsection to "Forms-Drawing Characters"; they
  render more than just lines, and Thomas Dickey has used the latter
  term for them in numerous ncurses release announcements.
* Clarify origin, abbreviation, and meaning of "ACS".
* Rename table column from "ACS Name" to "Symbol", since it refers to a
  C language symbol.
* Note that X/Open Curses specifies no error conditions.
* Cross reference putchar(3) in "SEE ALSO" section, not putc(3), since
  the former is what is mentioned in the page text.

Style:
* Speak primarily in terms of `waddch()` for convenience and because
  that is the core of the implementation.  Refer reader to ncurses(3x)
  regarding the usual set of variants.
* Consistently say "left margin", not "left edge".
* Tighten wording.
* Reorganize treatment of how `waddch()` handles what X/Open Curses
  terms "special characters" (backspace, tab, line feed, carriage
  return).
* Replace colon dangling at the end of a sentence with a period.  The
  subsequent use of bulleted paragraphs makes the structure clear.
* Use newly defined *roff strings (see below) to render carets and
  tildes.
* Use "that", not "which", with restrictive subordinate clauses.
* Set names of environment variables in italics, not bold.
* Prefer "check whether" over "check if".
  
<https://english.stackexchange.com/questions/9520/when-are-if-and-whether-equivalent>
* Recast portability admonition to use two bulleted paragraphs instead
  of one.  (If you need only one, why is it bulleted?)
* Favor active voice over passive.
* Prevent break within "System V".
* Favor "location" over "cell" when discussing screen contents.

Markup:
* Declare `'`, `^`, and `~` *roff strings to (portably and reliably)
  render an ASCII apostrophe (0x27), caret (0x5E), and tilde (0x7E),
  respectively.
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references (because
  man/make_sed.sh recognizes only certain patterns when rewriting such
  cross references).
* Protect literals from automatic hyphenation.
* Break input lines after commas.
* Refactor table format specification: use column modifiers to apply
  boldface to rows and columns instead repetitiously populating entries
  with font selection escape sequences.
* Use a single '_' in the table data to render a horizontal rule
  spanning the table.
* Use a dummy character to visibly mark empty table cells.
* Consistently set ACS symbol names (C preprocessor literals) in bold.

Also:
* man/man_db.renames.in: Rewrite new cross references.
---
 man/curs_addch.3x     | 458 ++++++++++++++++++++++++++++--------------
 man/man_db.renames.in |   2 +
 2 files changed, 305 insertions(+), 155 deletions(-)

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index f801e4385..dd57ae28f 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -33,12 +33,18 @@
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
+.ds '  \(aq
+.ds ^  \(ha
+.ds ~  \(ti
 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""
+.ds       '  '
+.ds       ^  ^
+.ds       ~  ~
 .\}
 .
 .de bP
@@ -67,94 +73,149 @@ .SH SYNOPSIS
 .fi
 .SH DESCRIPTION
 .SS "Adding Characters"
-The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put
-the character \fIch\fP into the given window at its current window position,
-which is then advanced.
-They are analogous to the standard C library's \fI\%putchar\fP(3).
-If the advance is at the right margin:
-.bP
-The cursor automatically wraps to the beginning of the next line.
+.B \%waddch
+puts the character
+.I ch
+at the cursor position of window
+.I win,
+then advances the cursor position,
+analogously to the standard C library's \fI\%putchar\fP(3).
+\fB\%ncurses\fP(3X) describes the variants of this function.
+.PP
+If advancement occurs at the right margin,
 .bP
-At the bottom of the current scrolling region,
-and if \fB\%scrollok\fP(3X) is enabled,
-the scrolling region is scrolled up one line.
+the cursor automatically wraps to the beginning of the next line;
+and
 .bP
-If \fB\%scrollok\fP(3X) is not enabled,
-writing a character at the lower right margin succeeds.
-However,
-an error is returned because it is not possible to wrap to a new line.
+at the bottom of the current scrolling region,
+and if \fB\%scrollok\fP(3X) is enabled for
+.I win,
+the scrolling region scrolls up one line.
 .PP
-If \fIch\fP is a tab, newline, carriage return or backspace,
-the cursor is moved appropriately within the window:
+If
+.I ch
+is a
+backspace,
+carriage return,
+line feed,
+or
+tab,
+the cursor moves appropriately within the window.
 .bP
-Backspace moves the cursor one character left; at the left
-edge of a window it does nothing.
+Backspace moves the cursor one character left;
+at the left margin of a window,
+it does nothing.
 .bP
-Carriage return moves the cursor to the window left margin on the current line.
+Carriage return moves the cursor to the left margin on the current line
+of the window.
 .bP
-Newline does a \fBclrtoeol\fP,
-then moves the cursor to the window left margin on the next line,
-scrolling the window if on the last line.
+Line feed does a \fB\%clrtoeol\fP(3X),
+then moves the cursor to the left margin on the next line of the window,
+scrolling the window if the cursor was already on the last line.
 .bP
-Tabs are considered to be at every eighth column.
-The tab interval may be altered by setting the \fBTABSIZE\fP variable.
+Tab advances the cursor to the next tab stop
+(possibly on the next line);
+these are placed at every eighth column by default.
+Alter the tab interval with the
+.B \%TABSIZE
+extension;
+see \fB\%curs_variables\fP(3X).
 .PP
-If \fIch\fP is any other nonprintable character,
+If
+.I ch
+is any other nonprintable character,
 it is drawn in printable form,
-using the same convention as \fB\%unctrl\fP(3X):
+using the same convention as \fB\%unctrl\fP(3X).
 .bP
-Control characters are displayed in the \fB^\fIX\fR notation.
+.B \%waddch
+displays control characters in
+.BI \*^ X
+notation.
 .bP
-Values above 128 are either meta characters
+Character codes above 127 are either meta characters
 (if the screen has not been initialized,
-or if \fB\%meta\fP(3X) has been called with a \fBTRUE\fP E parameter),
-shown in the \fBM\-\fIX\fR notation, or are displayed as themselves.
-In the latter case, the values may not be printable;
+or if \fB\%meta\fP(3X) has been called with a
+.B TRUE
+.I bf
+parameter)
+that render in
+.BI M\- X
+notation,
+or they display as themselves.
+In the latter case,
+the values may not be printable;
+.\" XXX: The following claim could be clearer.
 this follows the X/Open specification.
 .PP
-Calling \fBwinch\fP after adding a
-nonprintable character does not return the character itself,
-but instead returns the printable representation of the character.
+Calling \fB\%winch\fP(3X) on the location of a nonprintable character
+does not return the character itself,
+but its \fB\%unctrl\fP(3X) representation.
 .PP
 Video attributes can be combined with a character argument passed to
-\fBaddch\fP or related functions by logical-ORing them into the character.
-(Thus, text, including attributes, can be copied from one place to another
-using \fB\%inch\fP(3X) and \fBaddch\fP.)
-See the \fB\%curs_attr\fP(3X) page for values of predefined video
-attribute constants that can be usefully OR'ed into characters.
+.B \%waddch
+by logical-ORing them into the character.
+(Thus,
+text,
+including attributes,
+can be copied from one place to another using \fB\%winch\fP(3X) and
+.BR \%waddch .)
+See \fB\%curs_attr\fP(3X) for values of predefined video attribute
+constants that can be usefully OR'ed with characters.
 .SS "Echoing Characters"
-The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to
-\fBaddch\fP followed by a call to \fB\%refresh\fP(3X), or a call to 
\fBwaddch\fP
-followed by a call to \fBwrefresh\fP.
-The knowledge that only a single
-character is being output is used and, for non-control characters, a
-considerable performance gain may be seen by using these routines instead of
-their equivalents.
-.SS "Line Graphics"
-The following variables may be used to add line drawing characters to the
-screen with routines of the \fBaddch\fP family.
-The default character listed
-below is used if the \fBacsc\fP capability does not define a terminal-specific
-replacement for it,
-or if the terminal and locale configuration requires Unicode but the
-library is unable to use Unicode.
-.PP
-The names are taken from VT100 nomenclature.
+.B \%echochar
+and
+.B \%wechochar
+are equivalent to calling
+.RB \%( w ) addch
+followed by
+.RB \%( w ) refresh .
+.I curses
+interprets these functions as a hint that only a single character is
+being output;
+for non-control characters,
+a considerable performance gain may be enjoyed by employing them.
+.\" TODO: Combine the following with the "Line Drawing" subsection of
+.\" terminfo(5) and replace this with a cross reference there.
+.SS "Forms-Drawing Characters"
+.I curses
+defines macros starting with
+.B \%ACS_
+that can be used with
+.B \%waddch
+to write line-drawing and other special characters to the screen.
+.I \%ncurses
+terms these
+.I "forms-drawing characters."
+The ACS default listed below is used if the
+.B \%acs_chars
+.RB ( \%acsc )
+.I \%term\%info
+capability does not define a terminal-specific replacement for it,
+or if the terminal and locale configuration requires Unicode to access
+these characters but the library is unable to use Unicode.
+The \*(``acsc char\*('' column corresponds to how the characters are
+specified in the
+.B \%acs_chars
+string capability,
+and the characters in it may appear on the screen if the terminal's
+database entry incorrectly advertises ACS support.
+The name \*(``ACS\*('' originates in the Alternate Character Set feature
+of the DEC VT100 terminal.
 .PP
 .TS
-l l l l
-l l l l
-_ _ _ _
-l l l l.
-\fBACS\fP      \fBACS\fP       \fBacsc\fP      \fBGlyph\fP
-\fBName\fP     \fBDefault\fP   \fBchar\fP      \fBName\fP
+Lb Lb Lb Lb
+Lb Lb Lb Lb
+Lb L  L  Lx.
+\&     ACS     acsc    \&
+Symbol Default char    Glyph Name
+_
 ACS_BLOCK      #       0       solid square block
 ACS_BOARD      #       h       board of squares
 ACS_BTEE       +       v       bottom tee
-ACS_BULLET     o       ~       bullet
+ACS_BULLET     o       \*~     bullet
 ACS_CKBOARD    :       a       checker board (stipple)
 ACS_DARROW     v       .       arrow pointing down
-ACS_DEGREE     '       f       degree symbol
+ACS_DEGREE     \*'     f       degree symbol
 ACS_DIAMOND    +       \(ga    diamond
 ACS_GEQUAL     >       >       greater-than-or-equal-to
 ACS_HLINE      \-      q       horizontal line
@@ -176,7 +237,7 @@ .SS "Line Graphics"
 ACS_S9 \&_     s       scan line 9
 ACS_STERLING   f       }       pound-sterling symbol
 ACS_TTEE       +       w       top tee
-ACS_UARROW     ^       \-      arrow pointing up
+ACS_UARROW     \*^     \-      arrow pointing up
 ACS_ULCORNER   +       l       upper left-hand corner
 ACS_URCORNER   +       k       upper right-hand corner
 ACS_VLINE      |       x       vertical line
@@ -211,119 +272,206 @@ .SH RETURN VALUE
 .B ERR
 because it is not possible to wrap to a new line.
 .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(3X) and fail if the position is outside the window,
+or
+(for \*(``mvw\*('' functions)
+if the
+.I \%WINDOW
+pointer is null.
 .SH NOTES
-Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and
-\fBechochar\fP may be macros.
+.BR \%addch ,
+.BR \%mvaddch ,
+.BR \%mvwaddch ,
+and
+.B \%echochar
+may be implemented as macros.
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-The defaults specified for forms-drawing characters apply in the POSIX locale.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+The defaults specified for forms-drawing characters apply in the POSIX
+locale.
 .SS "ACS Symbols"
-X/Open Curses states that the \fBACS_\fP definitions are \fBchar\fP constants.
-For the wide-character implementation (see \fBcurs_add_wch\fP),
-there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants.
-Some implementations are problematic:
+X/Open Curses states that the
+.B \%ACS_
+definitions are
+.I char
+constants.
+.PP
+Some implementations are problematic.
 .bP
-Some implementations define the ACS symbols to a constant
-(such as Solaris), while others define those to entries in an array.
+Solaris
+.I curses,
+for example,
+define the ACS symbols as constants;
+others define them as elements of an array.
 .IP
-This implementation uses an array \fBacs_map\fP, as done in SVr4 curses.
-NetBSD also uses an array, actually named \fB_acs_char\fP, with a \fB#define\fP
+This implementation uses an array,
+.BR \%acs_map ,
+as did SVr4
+.I curses.
+NetBSD also uses an array,
+actually named
+.BR \%_acs_char ,
+with a
+.B \%#define
 for compatibility.
 .bP
-HP-UX curses equates some of the \fBACS_\fP symbols
-to the analogous \fBWACS_\fP symbols as if the \fBACS_\fP symbols were
-wide characters.
-The misdefined symbols are the arrows
-and other symbols which are not used for line-drawing.
+HP-UX
+.I curses
+equates some of the
+.B \%ACS_
+symbols to the analogous
+.B \%WACS_
+symbols as if the
+.B \%ACS_
+symbols were wide characters
+(see \fB\%curs_add_wch\fP(3X)).
+The misdefined symbols are the arrows and others that are not used for
+line drawing.
 .bP
-X/Open Curses (issues 2 through 7) has a typographical error
-for the ACS_LANTERN symbol, equating its \*(``VT100+ Character\*(''
-to \fBI\fP (capital I), while the header files for SVr4 curses
-and the various implementations use \fBi\fP (lowercase).
+X/Open Curses
+(Issues 2 through 7)
+has a typographical error
+for the
+.B \%ACS_LANTERN
+symbol, equating its \*(``VT100+ Character\*('' to \*(``I\*(''
+(capital I),
+while the header files for SVr4
+.I curses
+and other implementations use \*(``i\*(''
+(small i).
 .IP
-None of the terminal descriptions on Unix platforms use uppercase-I,
-except for Solaris (i.e., \fBscreen\fP's terminal description,
+None of the terminal descriptions on Unix platforms use uppercase I,
+except for Solaris
+(in its
+.I \%term\%info
+entry for \fI\%screen\fP(1),
 apparently based on the X/Open documentation around 1995).
-On the other hand, the terminal description \fIgs6300\fP
-(AT&T PC6300 with EMOTS Terminal Emulator) uses lowercase-i.
-.LP
+On the other hand,
+its
+.B \%gs6300
+(AT&T PC6300 with EMOTS Terminal Emulator)
+description uses lowercase i.
+.PP
 Some ACS symbols
-(ACS_S3,
-ACS_S7,
-ACS_LEQUAL,
-ACS_GEQUAL,
-ACS_PI,
-ACS_NEQUAL,
-ACS_STERLING)
-were not documented in
-any publicly released System V.
-However, many publicly available terminfos
-include \fBacsc\fP strings in which their key characters (pryz{|}) are
-embedded, and a second-hand list of their character descriptions has come
-to light.
-The ACS-prefixed names for them were invented for \fB\%ncurses\fP(3X).
-.LP
-The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants
-depend on
+.RB ( \%ACS_S3 ,
+.BR \%ACS_S7 ,
+.BR \%ACS_LEQUAL ,
+.BR \%ACS_GEQUAL ,
+.BR \%ACS_PI ,
+.BR \%ACS_NEQUAL ,
+and
+.BR \%ACS_STERLING )
+were not documented in any publicly released System\ V.
+However,
+many publicly available
+.I \%term\%info
+entries include
+.B \%acsc
+strings in which their key characters (pryz{|}) are embedded,
+and a second-hand list of their character descriptions has come to
+light.
+The
+.I \%ncurses
+developers invented ACS-prefixed names for them.
+.PP
+The
+.I displayed
+values of
+.B \%ACS_
+constants depend on
 .bP
-the library configuration,
-i.e.,
-\fI\%ncurses\fP versus \fI\%ncursesw\fP,
-where the latter is capable of displaying Unicode while the former is not, and
+the
+.I \%ncurses
+ABI\(emfor example,
+wide-character versus non-wide-character configurations
+(the former is capable of displaying Unicode while the latter is not),
+and
 .bP
-whether the \fIlocale\fP uses UTF-8 encoding.
-.LP
-In certain cases, the terminal is unable to display line-drawing characters
-except by using UTF-8
-(see the discussion of \fB\%NCURSES_NO_UTF8_ACS\fP in
-\fB\%ncurses\fP(3X)).
+whether the locale uses UTF-8 encoding.
+.PP
+In certain cases,
+the terminal is unable to display forms-drawing characters
+.I except
+by using UTF-8;
+see the discussion of the
+.I \%NCURSES_NO_UTF8_ACS
+environment variable in \fB\%ncurses\fP(3X)).
 .SS "Character Set"
-X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
-a single character.
-As discussed in \fB\%curs_attr\fP(3X), that character may have been
-more than eight bits in an SVr3 or SVr4 implementation,
-but in the X/Open Curses model, the details are not given.
-The important distinction between SVr4 curses and X/Open Curses is
-that the non-character information (attributes and color) was
-separated from the character information which is packed in a \fBchtype\fP
-to pass to \fBwaddch\fP.
+X/Open Curses assumes that the parameter passed to
+.B \%waddch
+contains a single character.
+As discussed in \fB\%curs_attr\fP(3X),
+that character may have been more than eight bits wide in an SVr3 or
+SVr4 implementation,
+but in the X/Open Curses model,
+the details are not given.
+The important distinction between SVr4
+.I curses
+and X/Open Curses is that the latter separates non-character information
+(attributes and color)
+from the character code,
+which are packed into a
+.I \%chtype
+for passage to
+.BR \%waddch .
 .PP
-In this implementation, \fBchtype\fP holds an eight-bit character.
-But \fI\%ncurses\fP allows multibyte characters to be passed in a
-succession of calls to \fBwaddch\fP.
-The other implementations do not do this;
-a call to \fBwaddch\fP passes exactly one character
-which may be rendered as one or more cells on the screen
-depending on whether it is printable.
+In
+.I \%ncurses,
+.I \%chtype
+holds an eight-bit character.
+But
+.I \%ncurses
+allows a multibyte character to be passed in a succession of calls to
+.BR \%waddch .
+Other implementations do not;
+a
+.B \%waddch
+call transmits exactly one character,
+which may be rendered in one or more screen locations depending on
+whether it is printable.
 .PP
 Depending on the locale settings,
-\fI\%ncurses\fP will inspect the byte passed in each call to \fBwaddch\fP,
-and check if the latest call will continue a multibyte sequence.
-When a character is \fIcomplete\fP,
-\fI\%ncurses\fP displays the character and moves to the next position in the 
screen.
+.I \%ncurses
+inspects the byte passed in each
+.B \%waddch
+call,
+and checks whether the latest call continues a multibyte sequence.
+When a character is
+.I complete,
+.I \%ncurses
+displays the character and advances the window's current location.
 .PP
 If the calling application interrupts the succession of bytes in
-a multibyte character by moving the current location (e.g., using \fBwmove\fP),
-\fI\%ncurses\fP discards the partially built character,
-starting over again.
+a multibyte character sequence by moving the current location
+(for example,
+with \fB\%wmove\fP(3X)),
+.I \%ncurses
+discards the incomplete character.
 .PP
 For portability to other implementations,
-do not rely upon this behavior:
+do not rely upon this behavior.
+Check whether a character can be represented as a single byte in the
+current locale.
 .bP
-check if a character can be represented as a single byte in the current locale
-before attempting call \fBwaddch\fP, and
+If it can,
+call either
+.B \%waddch
+or \fB\%wadd_wch\fP(3X).
 .bP
-call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
+If it cannot,
+use only
+\fB\%wadd_wch\fP(3X).
 .SS TABSIZE
-The
-.B TABSIZE
-variable is implemented in SVr4 and other versions of
-.I curses,
-but is not defined by X/Open Curses
-(see \fBcurs_variables\fP(3X)).
+SVr4 and other versions of
+.I curses
+implement the
+.B \%TABSIZE
+variable,
+but X/Open Curses does not specify it
+(see \fB\%curs_variables\fP(3X)).
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_addchstr\fP(3X),
@@ -334,7 +482,7 @@ .SH SEE ALSO
 \fB\%curs_outopts\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_variables\fP(3X),
-\fB\%putc\fP(3)
+\fB\%putchar\fP(3)
 .PP
 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
 .I \%ncurses
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 9a4971353..4c93825e7 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -182,6 +182,7 @@ bkgd.3x                             bkgd.3ncurses
 bkgrnd.3x                      bkgrnd.3ncurses
 cbreak.3x                      cbreak.3ncurses
 clearok.3x                     clearok.3ncurses
+clrtoeol.3x                    clrtoeol.3ncurses
 curs_set.3x                    curs_set.3ncurses
 curscr.3x                      curscr.3ncurses
 def_prog_mode.3x               def_prog_mode.3ncurses
@@ -270,6 +271,7 @@ wechochar.3x                        wechochar.3ncurses
 wget_wch.3x                    wget_wch.3ncurses
 wgetch.3x                      wgetch.3ncurses
 wgetstr.3x                     wgetstr.3ncurses
+winch.3x                       winch.3ncurses
 wins_wch.3x                    wins_wch.3ncurses
 winsch.3x                      winsch.3ncurses
 wmove.3x                       wmove.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature