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

[G. Branden Robinson]

Revise "NOTES" section.

Content:
* Make claim about the delay when disambiguating ESC from a function key
  escape sequence less precise; on AIX curses and ncurses, this delay is
  tunable via ESCDELAY.
* Observe that KEY_BACKSPACE might report as ^?.
* Tell reader how to find out what their terminal actually does (cross
  reference infocmp(1)).
* Explain difference between Return and Enter keys.
* Refer to terminfo capabilities by name (and code).
* Expand discussion of predefined key code list, contrasting the AT&T
  UNIX PC keyboard with that of the IBM PC/AT keyboard.  Advise the
  impatient console jockey which key codes they probably actually care
  about.
* Un-hedge claim about KEY_IC mapping, and note KEY_DC as well.  Things
  seem to have settled down in this area over the past 25 years.

Style:
* Favor active voice over passive.
* Use caret/`unctrl()` notation to refer to control characters.
* Parallelize wording with other recent ncurses man page revisions.

Markup:
* Define `^` *roff string to (portably and reliably) render an ASCII
  caret (0x5E).
* 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).
* Annotate examples of terminal type descriptions that illustrates
  caveats made above about certain function keys.

* man/man_db.renames.in: Rewrite cross references to newly mentioned
  pages.
---
 man/curs_getch.3x     | 141 ++++++++++++++++++++++++++++++------------
 man/man_db.renames.in |   2 +
 2 files changed, 103 insertions(+), 40 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index a1d8ecb16..1fc812d21 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -33,12 +33,14 @@
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
+.ds ^  \(ha
 .\}
 .el \{\
 .ie t .ds `` ``
 .el   .ds `` ""
 .ie t .ds '' ''
 .el   .ds '' ""
+.ds       ^  ^
 .\}
 .
 .ie \n(.g .ds : \:
@@ -464,55 +466,114 @@ .SH RETURN VALUE
 or
 .BR FALSE .
 .SH NOTES
-Use of the escape key by a programmer for a single character function is
-discouraged, as it will cause a delay of up to one second while the
-keypad code looks for a following function-key sequence.
+.I curses
+discourages assignment of the ESC key to a discrete function by the
+programmer because the library requires a delay while it awaits the
+potential remainder of a terminal escape sequence.
 .PP
-Some keys may be the same as commonly used control
-keys, e.g.,
-\fBKEY_ENTER\fP versus control/M,
-\fBKEY_BACKSPACE\fP versus control/H.
-Some curses implementations may differ according to whether they
-treat these control keys specially (and ignore the terminfo), or
-use the terminfo definitions.
-\fI\%ncurses\fP uses the terminfo definition.
-If it says that \fBKEY_ENTER\fP is control/M,
-\fBgetch\fP will return \fBKEY_ENTER\fP
-when you press control/M.
+Some key strokes are indistinguishable from control characters;
+for example,
+.B \%KEY_ENTER
+may be the same as
+.BR \*^M , \" as with att630 or pccon+keys
+and
+.B \%KEY_BACKSPACE
+may be the same as
+.B \*^H \" as with att505 or vt52-basic
+or
+.BR \*^? . \" as with pccon+keys or vt320
+Consult the terminal's
+.I \%term\%info
+entry to determine whether this is the case;
+see \fB\%infocmp\fP(1).
+Some
+.I curses
+implementations,
+including
+.I \%ncurses,
+honor the
+.I \%term\%info
+key definitions;
+others treat such control characters specially.
 .PP
-Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP
-key on the numeric keypad:
+.I curses
+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,
+like other function keys,
+is reliably recognized only if the window's keypad mode is enabled.
 .bP
-the terminal description lists the most useful keys,
+The
+.I \%term\%info
+.B \%key_enter
+.RB ( kent )
+capability describes the character (sequence) sent by the terminal's
+keypad Enter key.
 .bP
-the \fIEnter\fP key on the regular keyboard is already handled by
-the standard ASCII characters for carriage-return and line-feed,
+\*(``Enter or send\*('' is X/Open Curses's description of this key.
+.PP
+.I curses
+treats the Enter or Return key in the
+.I alphabetic
+section of the keyboard differently.
 .bP
-depending on whether \fBnl\fP or \fBnonl\fP was called,
-pressing \*(``Enter\*('' on the regular keyboard
-may return either a carriage-return or line-feed, and finally
+It usually produces a control code for carriage return
+.RB ( \*^M )
+or line feed
+.RB ( \*^J ).
 .bP
-\*(``Enter or send\*('' is the standard description for this key.
+Depending on the terminal mode
+(raw,
+cbreak,
+or
+\*(``cooked\*(''),
+and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called,
+.B \%wgetch
+may return either a carriage return or line feed upon an Enter or Return
+key stroke.
 .PP
-When using \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP, or
-\fBmvwgetch\fP, nocbreak mode (\fBnocbreak\fP) and echo mode
-(\fBecho\fP) should not be used at the same time.
-Depending on the
-state of the tty driver when each character is typed, the program may
-produce undesirable results.
+Use of
+.B \%wgetch
+with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X)
+is not well-defined.
 .PP
-Note that \fBgetch\fP, \fBmvgetch\fP, and \fBmvwgetch\fP may be macros.
+Historically,
+the list of key code macros above was influenced by the
+function-key-rich keyboard of the AT&T 7300
+(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.
+A
+.I curses
+application can expect such a keyboard to transmit key codes
+.BR \%KEY_UP ,
+.BR \%KEY_DOWN ,
+.BR \%KEY_LEFT ,
+.BR \%KEY_RIGHT ,
+.BR \%KEY_HOME ,
+.BR \%KEY_END ,
+.B \%KEY_PPAGE
+(Page Up),
+.B \%KEY_NPAGE
+(Page Down),
+.B \%KEY_IC
+(Insert),
+.B \%KEY_DC
+(Delete),
+and
+.BI \%KEY_F( n )
+for 1 \(<=
+.I n
+\(<= 12.
 .PP
-Historically, the set of keypad macros was largely defined by the extremely
-function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4.
-Modern
-personal computers usually have only a small subset of these.
-IBM PC-style
-consoles typically support little more than \fBKEY_UP\fP, \fBKEY_DOWN\fP,
-\fBKEY_LEFT\fP, \fBKEY_RIGHT\fP, \fBKEY_HOME\fP, \fBKEY_END\fP,
-\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12.
-The Ins key
-is usually mapped to \fBKEY_IC\fP.
+.BR \%getch ,
+.BR \%mvgetch ,
+and
+.B \%mvwgetch
+may be implemented as macros.
 .SH EXTENSIONS
 \fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
 and is not found in SVr4
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 5f0842a02..815f5d568 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -224,10 +224,12 @@ newwin.3x                 newwin.3ncurses
 nl.3x                          nl.3ncurses
 nocbreak.3x                    nocbreak.3ncurses
 nodelay.3x                     nodelay.3ncurses
+nonl.3x                                nonl.3ncurses
 notimeout.3x                   notimeout.3ncurses
 pnoutrefresh.3x                        pnoutrefresh.3ncurses
 prefresh.3x                    prefresh.3ncurses
 putwin.3x                      putwin.3ncurses
+raw.3x                         raw.3ncurses
 refresh.3x                     refresh.3ncurses
 reset_shell_mode.3x            reset_shell_mode.3ncurses
 restartterm.3x                 restartterm.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature