[PATCH 088/100] man/curs_getch.3x: Fix content, style, and markup nits.

[G. Branden Robinson]

Content:
* Stop saying "newline" when we mean "line feed".  A "newline" is,
  depending on context, an abstraction or U+0085, the "Next Line" C1
  control.  The discussion here is at the level of character codes.
* Recast to cut down on use of the word "keypad" to refer to multiple
  different things.

Style:
* Fix spurious capitalization.
* Elevate to a slightly higher register (e.g., "physical" vs. "real").
* Use idiomatic Unix/POSIX jargon regarding signal handling.  (Does
  "detecting" a signal mean you're not handling it?)
* Align "RETURN VALUE" boilerplate with model language in curs_insch.3x.

Markup:
* Protect man page topic literals from hyphenation.
---
 man/curs_getch.3x | 86 ++++++++++++++++++++++-------------------------
 1 file changed, 41 insertions(+), 45 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 21d89edf7..de19e6223 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -150,9 +150,7 @@ .SS "Reading Characters"
 .I c
 is a carriage return and \fBnl\fP(3X) has been called,
 .B \%wgetch
-returns the character code for newline
-(line feed)
-instead.
+returns the character code for line feed instead.
 .SS "Keypad Mode"
 To
 .IR curses ,
@@ -192,7 +190,7 @@ .SS "Keypad Mode"
 In
 .IR \%ncurses ,
 .I "user-defined function keys"
-are configured with \fBdefine_key\fP(3X);
+are configured with \fB\%define_key\fP(3X);
 they have no names,
 but are also expected to have values outside the range of eight-bit
 codes.
@@ -264,7 +262,7 @@ .SS "Predefined Key Codes"
 The naming convention may seem obscure,
 with some apparent misspellings
 (such as \*(``RSUME\*('' for \*(``resume\*('');
-The names correspond to the
+the names correspond to the
 .I \%term\%info
 capability names for the keys,
 and were standardized before the IBM PC/AT keyboard layout achieved a
@@ -378,7 +376,7 @@ .SS "Predefined Key Codes"
 .TE
 .RE
 .PP
-The keypad is arranged as follows.
+Many keyboards feature a nine-key directional pad.
 .PP
 .RS
 .TS
@@ -390,29 +388,29 @@ .SS "Predefined Key Codes"
 .TE
 .RE
 .sp
-Two of these symbols do
+Two of the symbols in the list above do
 .I not
-correspond to a real key.
+correspond to a physical key.
 .bP
 .B \%wgetch
 returns
-.B \%KEY_RESIZE
-(even if the window's keypad mode is disabled)
+.BR \%KEY_RESIZE ,
+even if the window's keypad mode is disabled,
 when
 .I \%ncurses
-detects the
+handles a
 .B \%SIGWINCH
 signal;
-see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X).
+see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X).
 .bP
 .B \%wgetch
 returns
 .B \%KEY_MOUSE
 to indicate that a mouse event is pending collection;
-see \fBcurs_mouse\fP(3X).
+see \fB\%curs_mouse\fP(3X).
 Receipt of this code requires a window's keypad mode to be enabled,
 because to interpret mouse input
-(as with with \fIxterm\fP(1)'s mouse prototocol),
+(as with with \fI\%xterm\fP(1)'s mouse prototocol),
 .I \%ncurses
 must read an escape sequence,
 as with a function key.
@@ -420,21 +418,29 @@ .SS "Testing Key Codes"
 In
 .IR \%ncurses ,
 .B \%has_key
-takes a key code value from the above list,
-and returns a Boolean value indicating the terminal's recognition of it.
+returns a Boolean value indicating whether the terminal type recognizes
+its parameter as a key code value.
 See also
-\fBdefine_key\fP(3X) and \fBkey_defined\fP(3X).
+\fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
 .SH RETURN VALUE
-.B \%wgetch
-returns
+Except for
+.BR \%has_key ,
+these functions return
+.B OK
+on success and
 .B ERR
-if
-.bP
-the
+on failure.
+.PP
+Functions taking a
 .I \%WINDOW
-pointer is
-.BR NULL ,
-or
+pointer argument fail if the pointer is
+.BR NULL .
+.PP
+Functions with a \*(``mv\*('' prefix first perform cursor movement using
+\fB\%wmove\fP(3X) and fail if the position is outside the window.
+.PP
+.B \%wgetch
+also fails if
 .bP
 its timeout expires without any data arriving,
 or
@@ -445,20 +451,8 @@ .SH RETURN VALUE
 is set to
 .BR \%EINTR .
 .PP
-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 win
-parameter is a null pointer.
-.PP
 .B \%ungetch
-returns
-.B OK
-on success and
-.B ERR
-if there is no more room in the input queue.
+fails if there is no more room in the input queue.
 .PP
 .B \%has_key
 returns
@@ -503,16 +497,18 @@ .SH NOTES
 distinguishes the Enter keys in the alphabetic and numeric keypad
 sections of a keyboard because (most) terminals do.
 .B \%KEY_ENTER
-refers to the key on the (numeric) keypad and,
+refers to the key on the numeric keypad and,
 like other function keys,
-is reliably recognized only if the window's keypad mode is enabled.
+and is reliably recognized only if the window's keypad mode is enabled.
 .bP
 The
 .I \%term\%info
 .B \%key_enter
 .RB ( kent )
-capability describes the character (sequence) sent by the terminal's
-keypad Enter key.
+capability describes the character (sequence) sent by the Enter key of
+a terminal's numeric
+(or similar)
+keypad.
 .bP
 \*(``Enter or send\*('' is X/Open Curses's description of this key.
 .PP
@@ -547,8 +543,8 @@ .SH NOTES
 (also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and
 \*(``UNIX PC\*(''),
 a 1985 machine.
-Today's computer keyboards are based on the IBM PC/AT keyboard and tend
-to have fewer.
+Today's computer keyboards are based that of the IBM PC/AT and tend to
+have fewer.
 A
 .I curses
 application can expect such a keyboard to transmit key codes
@@ -630,7 +626,7 @@ .SH PORTABILITY
 .I curses
 implementations,
 it varied depending on whether the operating system's dispatch of a
-signal to a handler interrupts a \fIread\fP(2) call in progress or not,
+signal to a handler interrupting a \fIread\fP(2) call in progress,
 and also
 (in some implementations)
 whether an input timeout or non-blocking mode has been set.
-- 
2.30.2

signature.asc
Description: PGP signature