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

[G. Branden Robinson]

Content:
* Migrate subsection headings to name ncurses functions, as is Thomas's
  preference and to align better with many other ncurses man pages.
* Drop redundant discussion of advancement from right margin at the end
  of the scrolling region.
* Clarify that the `ch` argument can be an expression (its integral type
  makes this easy).
* Improve terminological discipline: speak of "attributes" (essentially
  a bit vector) and "color pair identifier".
* Consistently present terminfo capability codes in parentheses after
  their names.
* Distinguish a "terminal" (individual devices that generally map
  one-to-one with a seated user) from a "terminal type" (which has a
  programming interface).
* Recast discussion of character encoding width.  X/Open Curses does not
  in fact mandate separation of attributes and color pair identifier
  from a character code in a chtype.

Style:
* Tighten wording.
* Recast fragmentary bulleted lists so that they read as sentences when
  considered with preceding material.
* Drop unnecessary commas.
* Migrate some uses of parenthetical clarifications to independent
  clauses after semicolons.
* Fix grammar nits (subject/verb agreement in number).

Markup:
* Quote second arguments to font alternation macros to prevent spurious
  warnings from one of Thomas's well-formedness checking scripts.
* Fix backwards font alternation macro.
---
 man/curs_addch.3x | 131 ++++++++++++++++++++++++----------------------
 1 file changed, 68 insertions(+), 63 deletions(-)

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 2ca0f8c6e..3c97adffb 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -72,22 +72,24 @@ .SH SYNOPSIS
 \fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
 .fi
 .SH DESCRIPTION
-.SS "Adding Characters"
+.SS waddch
 .B \%waddch
-puts the character
+writes the
+.I curses
+character
 .I ch
-at the cursor position of window
-.IR win ,
+to the window
+.IR 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
-the cursor automatically wraps to the beginning of the next line;
-and
+the cursor automatically wraps to the beginning of the next line,
+then,
 .bP
-at the bottom of the current scrolling region,
+if it was at the bottom of the scrolling region,
 and if \fB\%scrollok\fP(3X) is enabled for
 .IR win ,
 the scrolling region scrolls up one line.
@@ -110,10 +112,7 @@ .SS "Adding Characters"
 of the window.
 .bP
 Line feed does a \fB\%clrtoeol\fP(3X),
-then moves the cursor to the left margin on the next line of the window,
-and if \fB\%scrollok\fP(3X) is enabled for
-.IR win ,
-scrolls the window if the cursor was already on the last line.
+then advances as if from the right margin.
 .bP
 Tab advances the cursor to the next tab stop
 (possibly on the next line);
@@ -126,23 +125,22 @@ .SS "Adding Characters"
 If
 .I ch
 is any other nonprintable character,
-it is drawn in printable form,
-using the same convention as \fB\%unctrl\fP(3X).
+it is drawn in printable form using the same convention as
+\fB\%unctrl\fP(3X).
 .PP
 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
+The object or expression
 .I ch
-may contain rendering and/or color attributes,
-and others can be combined with the parameter
-by logically \*(``or\*(''ing with it.
+may contain attributes and/or a color pair identifier.
 (A character with its attributes can be copied from place to place
 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"
+.SS wechochar
 .B \%echochar
 and
 .B \%wechochar
@@ -177,8 +175,9 @@ .SS "Forms-Drawing Characters"
 The \*(``acsc char\*('' column corresponds to how the characters are
 specified in the
 .B \%acs_chars
+.RB ( \%acsc )
 string capability,
-and the characters in it may appear on the screen if the terminal's
+and the characters in it may appear on the screen if the terminal type's
 database entry incorrectly advertises ACS support.
 The name \*(``ACS\*('' originates in the Alternate Character Set feature
 of the DEC VT100 terminal.
@@ -235,33 +234,40 @@ .SH RETURN VALUE
 .B \%waddch
 returns
 .B ERR
-if it is not possible to add a complete character at the cursor
-position,
-as when conversion of a multibyte character to a byte sequence fails,
-or at least one of the resulting bytes cannot be added to the window.
+if
+.bP
+.I win
+is
+.BR NULL ","
+.bP
+wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
+not been called on
+.I win
+when a write to its bottom right location is attempted,
+or
+.bP
+it is not possible to add a complete character at the cursor position.
+.PP
+The last may be due to different causes:
+.bP
+conversion of a multibyte character to a byte sequence can fail,
+or
+.bP
+at least one of the bytes resulting from conversion from a multibyte
+sequence cannot be added to the window.
 See section \*(``PORTABILITY\*('' below regarding the use of
 .B \%waddch
 with multibyte characters.
 .PP
-.B \%waddch
-can successfully write a character at the bottom right location of the
-window.
-However,
-.I \%ncurses
-returns
-.B ERR
-if \fB\%scrollok\fP(3X) is not enabled in that event,
-because it is not possible to wrap to a new line.
-.PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
 .RI ( y ,
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-.BR \%addch ,
-.BR \%mvaddch ,
-.BR \%mvwaddch ,
+.BR \%addch ","
+.BR \%mvaddch ","
+.BR \%mvwaddch ","
 and
 .B \%echochar
 may be implemented as macros.
@@ -272,8 +278,8 @@ .SS TABSIZE
 implement the
 .B \%TABSIZE
 variable,
-but X/Open Curses does not specify it
-(see \fB\%curs_variables\fP(3X)).
+but X/Open Curses does not specify it;
+see \fB\%curs_variables\fP(3X).
 .SH PORTABILITY
 X/Open Curses,
 Issue 4 describes these functions.
@@ -299,7 +305,7 @@ .SS "ACS Symbols"
 Solaris
 .IR curses ,
 for example,
-define the ACS symbols as constants;
+defines the ACS symbols as constants;
 others define them as elements of an array.
 .IP
 This implementation uses an array,
@@ -365,8 +371,8 @@ .SS "ACS Symbols"
 .I \%term\%info
 entries include
 .B \%acsc
-strings in which their key characters
-.BR ( pryz{|} )
+capabilities in which their key characters
+.RB ( pryz{|} )
 are embedded,
 and a second-hand list of their character descriptions has come to
 light.
@@ -395,51 +401,50 @@ .SS "ACS Symbols"
 by using UTF-8;
 see the discussion of the
 .I \%NCURSES_NO_UTF8_ACS
-environment variable in \fB\%ncurses\fP(3X)).
+environment variable in \fB\%ncurses\fP(3X).
 .SS "Character Set"
 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
+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 SVr4 packs into a
+but X/Open Curses leaves the width of a non-wide character code
+unspecified.
+The standard further does not specify the internal structure of a
+.IR chtype ","
+though the use of bit operations to combine the character code with
+attributes and a color pair identifier into a
 .I \%chtype
 for passage to
-.BR \%waddch .
+.B \%waddch
+is common.
+A portable application uses only the macros discussed in
+\fB\%curs_attr\fP(3X) to manipulate a
+.IR \%chtype "."
 .PP
 In
 .IR \%ncurses ,
 .I \%chtype
-holds an eight-bit character.
-But the library allows a multibyte character to be passed in a
+holds an eight-bit character,
+but the library allows a multibyte character to be passed in a
 succession of calls to
-.BR \%waddch .
+.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,
+whether it is printable
+(see \fB\%unctrl\fP(3X)).
+Depending on the locale,
 .I \%ncurses
 inspects the byte passed in each
 .B \%waddch
-call,
-and checks whether the latest call continues a multibyte sequence.
+call and checks whether the latest call continues a multibyte sequence.
 When a character is
-.IR complete ,
+.IR complete ","
 .I \%ncurses
 displays the character and advances the cursor.
-.PP
 If the calling application interrupts the succession of bytes in
 a multibyte character sequence by changing the current location\(emfor
 example,
@@ -448,7 +453,7 @@ .SS "Character Set"
 discards the incomplete character.
 .PP
 For portability to other implementations,
-do not rely upon this behavior.
+do not rely upon the foregoing behavior.
 Check whether a character can be represented as a single byte in the
 current locale.
 .bP
-- 
2.30.2

signature.asc
Description: PGP signature