[PATCH 16/17] man/curs_getch.3x: Revise (8/8).

[G. Branden Robinson]

Revise "PORTABILITY" and "SEE ALSO" sections.

Content:
* Generalize reference to X/Open Curses, Issue 4.  It's probably not
  necessary to specify "Version 2" here, according to that document,
  these (pretty fundamental) functions came in with Issue _2_, but I
  cannot find a copy of that online.
* Observe that PDCurses and NetBSD curses support the ncurses extensions
  documented here.
* Add cross reference to curs_addch.3x since it's important for
  predicting behavior of `wgetch()` with `echo()`.

Style:
* Parallelize wording with other recent ncurses man page revisions.
* Gather discussion of signal handling into one paragraph.  (It had been
  interrupted by material on KEY_MOUSE and KEY_RESIZE extensions).

Markup:
* 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 hyphenation.
* Set "curses" in italics, not roman.
* Annotate source material for PDCurses and NetBSD curses claims.
---
 man/curs_getch.3x | 60 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 39 insertions(+), 21 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index ad79506f9..a45d99fba 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -601,32 +601,50 @@ .SH PORTABILITY
 .B \%NCURSES_VERSION
 preprocessor macro.
 .PP
-X/Open Curses, Issue 4, Version 2, describes
+X/Open Curses, Issue 4, describes
 \fB\%getch\fP,
 \fB\%wgetch\fP,
 \fB\%mvgetch\fP,
 \fB\%mvwgetch\fP,
 and
 \fB\%ungetch\fP.
-They read single-byte characters only.
-The standard specifies that they return \fBERR\fP on failure,
-but describes no failure conditions.
+It specifies no error conditions for them.
+.PP
+.B \%wgetch
+reads only single-byte characters.
 .PP
 The echo behavior of these functions on input of
 .B KEY_
 or backspace characters was not specified in the SVr4 documentation.
 This description is adapted from X/Open Curses.
 .PP
-The behavior of \fBgetch\fP and friends in the presence of signal
-handlers is unspecified in the SVr4 documentation and X/Open Curses.
-Under historical curses implementations,
+The behavior of
+.B \%wgetch
+in the presence of signal handlers is unspecified in the SVr4
+documentation and X/Open Curses.
+In historical
+.I curses
+implementations,
 it varied depending on whether the operating system's dispatch of a
-signal to a handler interrupts a \fBread\fP(2) call in progress or not,
+signal to a handler interrupts a \fIread\fP(2) call in progress or not,
 and also
 (in some implementations)
 whether an input timeout or non-blocking mode has been set.
+Programmers concerned about portability should be prepared for either of
+two cases:
+(a) signal receipt does not interrupt
+.BR \%wgetch ;
+or
+(b) signal receipt interrupts
+.B \%wgetch
+and causes it to return
+.B ERR
+with
+.B \%errno
+set to
+.BR \%EINTR .
 .PP
-.B KEY_MOUSE
+.B \%KEY_MOUSE
 is mentioned in X/Open Curses,
 along with a few related
 .I \%term\%info
@@ -636,23 +654,23 @@ .SH PORTABILITY
 .I \%ncurses
 is an extension.
 .PP
-.B KEY_RESIZE
-is an extension first implemented for
+.B \%KEY_RESIZE
+and
+.B \%has_key
+are extensions first implemented for
 .I \%ncurses.
+By 2022,
+.I \%PDCurses
+.\" 
https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
+and
 NetBSD
 .I curses
-later added this extension.
-.PP
-Programmers concerned about portability should be prepared for either of two
-cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt
-interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set 
to
-\fBEINTR\fP.
-.PP
-The \fBhas_key\fP function is unique to \fI\%ncurses\fP.
-We recommend that
-any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature 
macro.
+.\" 
https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
+had added them along with
+.B \%KEY_MOUSE.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
 \fB\%curs_inopts\fP(3X),
 \fB\%curs_mouse\fP(3X),
 \fB\%curs_move\fP(3X),
-- 
2.30.2

signature.asc
Description: PGP signature