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

[G. Branden Robinson]

Content:
* Clarify what one can expect from the encoding of the integer returned
  by `wgetch()`.  Point out effect of control key.
* Rewrite discussion of behavior when `wgetch()` applies to a non-pad
  window and `echo()` has been called.
* Drop claim that performance of a line feed has anything to do with
  `wgetch()`; that's (ultimately) `waddch()`'s job.
* Clarify that `nl()` affects only how `wgetch()` alters its return
  value and not any other behavior.
* Thanks to Thomas Dickey and Gabriel Ravier for discussion of the
  foregoing points.

Style:
* Speak primarily in terms of `wgetch()` for convenience and because
  that is the core of the implementation.  Refer reader to ncurses(3x)
  regarding the usual set of variants.
* Speak more precisely, in terms of key strokes, terminal keyboards
  being associated with windows (cf. the windows themselves), and so on.
* Make more reference to the parameters named in the function synopses.
* Favor active voice over passive.
* Favor present tense over future.

Markup:
* Annotate inconsistent placement of `has_key()` extension document.
  Further, giving that function its own page would avoid the problem of
  recapitulating it in curs_get_wch.3x or having to make a cross
  reference from a wide-character API page to a non-wide page.
* 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).

* man/man_db.renames.in: Rewrite cross references to several newly
  mentioned pages.
---
 man/curs_getch.3x     | 82 ++++++++++++++++++++++++++++++-------------
 man/man_db.renames.in |  7 ++++
 2 files changed, 65 insertions(+), 24 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index cc189523f..844d3e5a6 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -64,29 +64,60 @@ .SH SYNOPSIS
 .PP
 .B int ungetch(int \fIch\fP);
 .PP
+.\" XXX: Move has_key into its own page like define_key and key_defined?
 \fI/* extension */\fP
 .B int has_key(int \fIch\fP);
 .fi
 .SH DESCRIPTION
 .SS "Reading Characters"
-The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read
-a character from the window.
-In no-delay mode, if no input is waiting, the value \fBERR\fP is returned.
-In delay mode, the program waits until the system
-passes text through to the program.
-Depending on the setting of \fBcbreak\fP,
-this is after one character (cbreak mode),
-or after the first newline (nocbreak mode).
-In half-delay mode,
-the program waits until a character is typed or the
-specified timeout has been reached.
+.B \%wgetch
+gathers a key stroke from the terminal keyboard associated with a
+.I curses
+window
+.I win.
+\fB\%ncurses\fP(3X) describes the variants of this function.
+.PP
+When input is pending,
+.B \%wgetch
+returns an integer identifying the key stroke;
+for alphanumeric and punctuation keys,
+this value corresponds to the character encoding used by the terminal.
+Use of the control key as a modifier often results in a distinct code.
+The behavior of other keys depends on whether
+.I win
+is in keypad mode;
+see subsection \*(``Keypad Mode\*('' below.
+.PP
+If no input is pending,
+then if the no-delay flag is set in the window
+(see \fB\%nodelay\fP(3X)),
+the function returns
+.BR ERR ;
+otherwise,
+.I curses
+waits until the terminal has input.
+If \fB\%cbreak\fP(3X)
+has been called,
+this happens after one character is read.
+If \fB\%nocbreak\fP(3X)
+has been called,
+it occurs when the next newline is read.
+If \fB\%halfdelay\fP(3X)
+has been called,
+.I curses
+waits until a character is typed or the specified delay elapses.
 .PP
-If \fBecho\fP is enabled, and the window is not a pad,
-then the character will also be echoed into the
-designated window according to the following rules:
+If \fB\%echo\fP(3X) has been called,
+and the window is not a pad,
+.I curses
+writes the returned character
+.I ch
+to the window
+(at the cursor position)
+per the following rules.
 .bP
 If
-the character value
+.I ch
 matches the terminal's erase character,
 the cursor moves leftward one position
 and the new position is erased
@@ -100,20 +131,23 @@ .SS "Reading Characters"
 .bP
 .I curses
 writes any other
-character value
+.I ch
 to the window,
 as with \fB\%wechochar\fP(3X).
 .bP
-If
-the character value
-is a carriage return,
-and if \fBcbreak\fP(3X) and \fBnl\fP(3X) have both been called,
+If the window has been moved or modified since the last call to
+\fB\%wrefresh\fP(3X),
 .I curses
-also performs a line feed.
+calls
+.BR \%wrefresh .
 .PP
-If the window is not a pad, and it has been moved or modified since the last
-call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character
-is read.
+If
+.I ch
+is a carriage return and \fBnl\fP(3X) has been called,
+.B \%wgetch
+returns the character code for newline
+(line feed)
+instead.
 .SS "Keypad Mode"
 If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for
 that function key is returned instead of the raw characters:
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 19a5c7494..5f0842a02 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -180,6 +180,7 @@ attron.3x                   attron.3ncurses
 baudrate.3x                    baudrate.3ncurses
 bkgd.3x                                bkgd.3ncurses
 bkgrnd.3x                      bkgrnd.3ncurses
+cbreak.3x                      cbreak.3ncurses
 clearok.3x                     clearok.3ncurses
 curs_set.3x                    curs_set.3ncurses
 curscr.3x                      curscr.3ncurses
@@ -190,6 +191,7 @@ delay_output.3x                     delay_output.3ncurses
 delscreen.3x                   delscreen.3ncurses
 derwin.3x                      derwin.3ncurses
 doupdate.3x                    doupdate.3ncurses
+echo.3x                                echo.3ncurses
 endwin.3x                      endwin.3ncurses
 extended_slk_color.3x          extended_slk_color.3ncurses
 filter.3x                      filter.3ncurses
@@ -199,6 +201,7 @@ getattr.3x                  getattr.3ncurses
 getcchar.3x                    getcchar.3ncurses
 getch.3x                       getch.3ncurses
 getwin.3x                      getwin.3ncurses
+halfdelay.3x                   halfdelay.3ncurses
 has_key.3x                     has_key.3ncurses
 idcok.3x                       idcok.3ncurses
 idlok.3x                       idlok.3ncurses
@@ -218,6 +221,8 @@ mvwin.3x                    mvwin.3ncurses
 newpad.3x                      newpad.3ncurses
 newterm.3x                     newterm.3ncurses
 newwin.3x                      newwin.3ncurses
+nl.3x                          nl.3ncurses
+nocbreak.3x                    nocbreak.3ncurses
 nodelay.3x                     nodelay.3ncurses
 notimeout.3x                   notimeout.3ncurses
 pnoutrefresh.3x                        pnoutrefresh.3ncurses
@@ -257,6 +262,8 @@ wattr_set.3x                        wattr_set.3ncurses
 wattrset.3x                    wattrset.3ncurses
 wbkgdset.3x                    wbkgdset.3ncurses
 wbkgrndset.3x                  wbkgrndset.3ncurses
+wdelch.3x                      wdelch.3ncurses
+wechochar.3x                   wechochar.3ncurses
 wget_wch.3x                    wget_wch.3ncurses
 wgetch.3x                      wgetch.3ncurses
 wgetstr.3x                     wgetstr.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature