[PATCH 11/11] man/curs_inch.3x: Revise.

[G. Branden Robinson]

Content:
* Continue terminological reform: say simply "attributes" rather than
  "rendering attibutes".
* Fix incomplete discussion in "RETURN VALUE" section.
* Relocate material; discuss what happens when `winch()` is applied to a
  window of complex characters in "NOTES" rather than "RETURN VALUE",
  since X/Open Curses doesn't mandate ncurses's behavior.  (As I read
  it, the standard would tolerate failing with ERR in this scenario.)

Style:
* Put a space after pointer star in function synopsis.
* Recast "HISTORY" section.
---
 man/curs_inch.3x | 75 +++++++++++++++++++++++++++++-------------------
 1 file changed, 46 insertions(+), 29 deletions(-)

diff --git a/man/curs_inch.3x b/man/curs_inch.3x
index 7046e8934..26ff30bdf 100644
--- a/man/curs_inch.3x
+++ b/man/curs_inch.3x
@@ -56,16 +56,16 @@ .SH SYNOPSIS
 \fB#include <curses.h>
 .PP
 \fBchtype inch(void);
-\fBchtype winch(WINDOW *\fIwin\fP);
+\fBchtype winch(WINDOW * \fIwin\fP);
 \fBchtype mvinch(int \fIy\fP, int \fIx\fP);
-\fBchtype mvwinch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+\fBchtype mvwinch(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP);
 .fi
 .SH DESCRIPTION
 .B \%winch
 returns the
 .I curses
 character,
-including rendering attributes and color pair identifier,
+including its attributes and color pair identifier,
 at the cursor position in the window
 .IR win "."
 Subsection \*(``Video Attributes\*('' of \fB\%attron\fP(3X) explains
@@ -73,26 +73,42 @@ .SH DESCRIPTION
 .IR chtype "."
 \fB\%ncurses\fP(3X) describes the variants of this function.
 .SH RETURN VALUE
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+In
+.IR \%ncurses ","
+.B \%winch
+returns
+.B ERR
+if
+.I win
+is
+.BR NULL "."
+.PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
 .RI ( y ,
 .IR x )
 is outside the window boundaries.
-.PP
-These functions do not return an error if the window comprises cells of
-.I curses
-complex characters
-(that is,
-they contain characters with codes wider than eight bits,
-or greater than 255 as an unsigned decimal integer).
-They instead extract only the low-order eight bits of character data
-in the cell.
 .SH NOTES
 .BR \%inch ,
 .BR \%mvinch ,
 and
 .B \%mvwinch
 may be implemented as macros.
+.PP
+These functions do not return an error if the window contains cells of
+.I curses
+complex characters;
+that is,
+if they contain characters with codes wider than eight bits
+(or greater than 255 as an unsigned decimal integer).
+They instead extract only the low-order eight bits of the character code
+from the cell.
 .SH PORTABILITY
 X/Open Curses,
 Issue 4 describes these functions.
@@ -100,25 +116,24 @@ .SH PORTABILITY
 .SH HISTORY
 The original
 .I curses
-in 4BSD
-(November 1980)
-implemented
+in 4BSD (1980) defined
 .I \%winch
-as a macro accessing the window structure member representing character
-cell data,
+as a macro accessing the
+.I \%WINDOW
+structure member representing character cell data,
 at that time a
 .IR char ","
-containing only a 7-bit character code
-and a \*(``standout\*(`` attribute bit
-(the only one it supported),
-masking off the latter.
+containing only a 7-bit ASCII character code
+and a \*(``standout\*(`` attribute bit,
+the only one the library supported.
 .PP
 SVr2
 .I curses
 (1984)
-extended the same approach,
-permitting several attributes to be combined with a character code by
-storing them together in a
+extended this approach,
+widening the character code to eight bits
+and permitting several attributes to be combined with it
+by storing them together in a
 .IR \%chtype ","
 an alias of
 .IR "unsigned short" "."
@@ -126,8 +141,8 @@ .SH HISTORY
 .\" builders to change the typedef to `char` or `long` as desired.  More
 .\" innocent times with respect to ABI compatibility concerns... --GBR
 Because a macro was used,
-its value was not type-checked as a function return value could have
-been.
+its value was not type-checked
+as a function return value could have been.
 Goodheart documented SVr3 (1987)
 .I \%winch
 as returning an
@@ -137,8 +152,10 @@ .SH HISTORY
 .I \%chtype
 became an alias of
 .IR "unsigned long" ","
-widening it in practical terms to 32 bits,
-as 64-bit Unix systems were not yet in wide use.
+using 16 bits for the character code and
+widening the type in practical terms to 32 bits,
+as 64-bit Unix systems were not yet in wide use,
+and fixed-width integral types would not be standard until ISO C99.
 .\" Cray's UNICOS was 1985 (how many shops had Crays?).  DEC OSF/1 for
 .\" the Alpha arrived in 1993.  --GBR
 SVr3.2 (1988)
@@ -153,7 +170,7 @@ .SH HISTORY
 .I \%ncurses
 uses eight bits for the character code.
 An application requiring a wider character type,
-for instance to handle Unicode,
+for instance to represent Unicode,
 should use the wide-character counterparts of these functions.
 .SH SEE ALSO
 \fB\%curs_in_wch\fP(3X) describes comparable functions of the
-- 
2.30.2

signature.asc
Description: PGP signature