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

[G. Branden Robinson]

Revise discussion of ungetting characters and predefined key codes.

Content:
* Throw more light on why there are key codes for keycaps the reader has
  likely never heard of.

Style:
* Recast.
* Drop angle bracket notation from "inline" header file names, set them
  in italics instead of bold, and protect them from automatic
  hyphenation.
* Revise table of keycodes.
  - Convert from slash as a tab character (which we can usefully employ
    in table entries) to literal tabs.
  - Refactor table format specification: use column modifiers to set
    heading rows in bold instead of populating every entry in them with
    font selection escape sequences.  Use 'x' column modifier to let the
    lengthy "Key name" column stretch to fit the page.
  - Use row spanning to present the arrow keys.  Consequently drop
    poorly typeset ellipsis.
  - Recast descriptions of keys, favoring words over abbreviations.
  - Group all the codes for shifted keys together.  Place them under a
    single rule.  Consequently promote the single rule under the column
    headings to a double one (only visible as such on typesetters).
* Revise table depicting directional keypad.
  - Convert from slash as a tab character (which we can usefully employ
    in table entries) to literal tabs.
  - Center the table.
  - Stop boldfacing every entry in the table.  When everything is
    emphasized, nothing is emphasized.
* Replace colon dangling at the ends of sentences with a period.  The
  subsequent use of bulleted paragraphs makes the structure clear.
* Favor active voice over passive.

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 potential future relocation of material (key code list).
---
 man/curs_getch.3x | 280 +++++++++++++++++++++++++---------------------
 1 file changed, 153 insertions(+), 127 deletions(-)

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 764538c63..54ab34ac6 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -240,154 +240,180 @@ .SS "Keypad Mode"
 further typing \*(``awakens\*(''
 .I curses.
 .SS "Ungetting Characters"
-The \fBungetch\fP routine places \fIch\fP back onto the input queue to be
-returned by the next call to \fBwgetch\fP.
-There is just one input queue for all windows.
+.B \%ungetch
+places
+.I ch
+into the input queue to be returned by the next call to
+.BR \%wgetch .
+A single input queue serves all windows.
 .SS "Predefined Key Codes"
-The following special keys are defined in \fB<curses.h>\fP.
+The header file
+.I \%curses.h
+defines the following function key codes.
 .bP
-Except for the special case \fBKEY_RESIZE\fP,
-it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes.
+Except for the special case of
+.BR \%KEY_RESIZE ,
+a window's keypad mode must be enabled for
+.B \%wgetch
+to read these codes from it.
 .bP
 Not all of these are necessarily supported on any particular terminal.
 .bP
-The naming convention may seem obscure, with some apparent
-misspellings (such as \*(``RSUME\*('' for \*(``resume\*('').
-The names correspond to the long terminfo capability names for the keys,
-and were defined long ago, in the 1980s.
+The naming convention may seem obscure,
+with some apparent misspellings
+(such as \*(``RSUME\*('' for \*(``resume\*('');
+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
+dominant position in industry.
 .PP
 .RS
+.\" XXX: Move this list into ncurses(3X), rather than duplicating it in
+.\" get_wch(3X) or having that page cross reference this one?
 .TS
-tab(/) ;
-l l .
-\fBName\fP/\fBKey\fP \fBname\fP
-_
-KEY_BREAK/Break key
-KEY_DOWN/The four arrow keys ...
-KEY_UP
-KEY_LEFT
-KEY_RIGHT
-KEY_HOME/Home key (upward+left arrow)
-KEY_BACKSPACE/Backspace
-KEY_F0/T{
-Function keys; space for 64 keys is reserved.
+Lb Lb
+Lb Lx.
+Symbol Key name
+=
+KEY_BREAK      Break key
+KEY_DOWN       Arrow keys
+KEY_UP \^
+KEY_LEFT       \^
+KEY_RIGHT      \^
+KEY_HOME       Home key (upward+left arrow)
+KEY_BACKSPACE  Backspace
+KEY_F0 T{
+Function keys; space for 64 keys is reserved
 T}
-KEY_F(\fIn\fP)/T{
-For 0 \(<= \fIn\fP \(<= 63
+KEY_F(\fIn\fP) T{
+Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
 T}
-KEY_DL/Delete line
-KEY_IL/Insert line
-KEY_DC/Delete character
-KEY_IC/Insert char or enter insert mode
-KEY_EIC/Exit insert char mode
-KEY_CLEAR/Clear screen
-KEY_EOS/Clear to end of screen
-KEY_EOL/Clear to end of line
-KEY_SF/Scroll 1 line forward
-KEY_SR/Scroll 1 line backward (reverse)
-KEY_NPAGE/Next page
-KEY_PPAGE/Previous page
-KEY_STAB/Set tab
-KEY_CTAB/Clear tab
-KEY_CATAB/Clear all tabs
-KEY_ENTER/Enter or send
-KEY_SRESET/Soft (partial) reset
-KEY_RESET/Reset or hard reset
-KEY_PRINT/Print or copy
-KEY_LL/Home down or bottom (lower left)
-KEY_A1/Upper left of keypad
-KEY_A3/Upper right of keypad
-KEY_B2/Center of keypad
-KEY_C1/Lower left of keypad
-KEY_C3/Lower right of keypad
-KEY_BTAB/Back tab key
-KEY_BEG/Beg(inning) key
-KEY_CANCEL/Cancel key
-KEY_CLOSE/Close key
-KEY_COMMAND/Cmd (command) key
-KEY_COPY/Copy key
-KEY_CREATE/Create key
-KEY_END/End key
-KEY_EXIT/Exit key
-KEY_FIND/Find key
-KEY_HELP/Help key
-KEY_MARK/Mark key
-KEY_MESSAGE/Message key
-KEY_MOUSE/Mouse event occurred
-KEY_MOVE/Move key
-KEY_NEXT/Next object key
-KEY_OPEN/Open key
-KEY_OPTIONS/Options key
-KEY_PREVIOUS/Previous object key
-KEY_REDO/Redo key
-KEY_REFERENCE/Ref(erence) key
-KEY_REFRESH/Refresh key
-KEY_REPLACE/Replace key
-KEY_RESIZE/Screen resized
-KEY_RESTART/Restart key
-KEY_RESUME/Resume key
-KEY_SAVE/Save key
-KEY_SBEG/Shifted beginning key
-KEY_SCANCEL/Shifted cancel key
-KEY_SCOMMAND/Shifted command key
-KEY_SCOPY/Shifted copy key
-KEY_SCREATE/Shifted create key
-KEY_SDC/Shifted delete char key
-KEY_SDL/Shifted delete line key
-KEY_SELECT/Select key
-KEY_SEND/Shifted end key
-KEY_SEOL/Shifted clear line key
-KEY_SEXIT/Shifted exit key
-KEY_SFIND/Shifted find key
-KEY_SHELP/Shifted help key
-KEY_SHOME/Shifted home key
-KEY_SIC/Shifted insert key
-KEY_SLEFT/Shifted left arrow key
-KEY_SMESSAGE/Shifted message key
-KEY_SMOVE/Shifted move key
-KEY_SNEXT/Shifted next key
-KEY_SOPTIONS/Shifted options key
-KEY_SPREVIOUS/Shifted prev key
-KEY_SPRINT/Shifted print key
-KEY_SREDO/Shifted redo key
-KEY_SREPLACE/Shifted replace key
-KEY_SRIGHT/Shifted right arrow key
-KEY_SRSUME/Shifted resume key
-KEY_SSAVE/Shifted save key
-KEY_SSUSPEND/Shifted suspend key
-KEY_SUNDO/Shifted undo key
-KEY_SUSPEND/Suspend key
-KEY_UNDO/Undo key
+KEY_DL Delete line
+KEY_IL Insert line
+KEY_DC Delete character
+KEY_IC Insert character/Enter insert mode
+KEY_EIC        Exit insert character mode
+KEY_CLEAR      Clear screen
+KEY_EOS        Clear to end of screen
+KEY_EOL        Clear to end of line
+KEY_SF Scroll one line forward
+KEY_SR Scroll one line backward (reverse)
+KEY_NPAGE      Next page/Page up
+KEY_PPAGE      Previous page/Page down
+KEY_STAB       Set tab
+KEY_CTAB       Clear tab
+KEY_CATAB      Clear all tabs
+KEY_ENTER      Enter/Send
+KEY_SRESET     Soft (partial) reset
+KEY_RESET      (Hard) reset
+KEY_PRINT      Print/Copy
+KEY_LL Home down/Bottom (lower left)
+KEY_A1 Upper left of keypad
+KEY_A3 Upper right of keypad
+KEY_B2 Center of keypad
+KEY_C1 Lower left of keypad
+KEY_C3 Lower right of keypad
+KEY_BTAB       Back tab key
+KEY_BEG        Beg(inning) key
+KEY_CANCEL     Cancel key
+KEY_CLOSE      Close key
+KEY_COMMAND    Cmd (command) key
+KEY_COPY       Copy key
+KEY_CREATE     Create key
+KEY_END        End key
+KEY_EXIT       Exit key
+KEY_FIND       Find key
+KEY_HELP       Help key
+KEY_MARK       Mark key
+KEY_MESSAGE    Message key
+KEY_MOUSE      Mouse event occurred
+KEY_MOVE       Move key
+KEY_NEXT       Next object key
+KEY_OPEN       Open key
+KEY_OPTIONS    Options key
+KEY_PREVIOUS   Previous object key
+KEY_REDO       Redo key
+KEY_REFERENCE  Ref(erence) key
+KEY_REFRESH    Refresh key
+KEY_REPLACE    Replace key
+KEY_RESIZE     Screen resized
+KEY_RESTART    Restart key
+KEY_RESUME     Resume key
+KEY_SAVE       Save key
+KEY_SELECT     Select key
+KEY_SUSPEND    Suspend key
+KEY_UNDO       Undo key
+_
+KEY_SBEG       Shifted beginning key
+KEY_SCANCEL    Shifted cancel key
+KEY_SCOMMAND   Shifted command key
+KEY_SCOPY      Shifted copy key
+KEY_SCREATE    Shifted create key
+KEY_SDC        Shifted delete character key
+KEY_SDL        Shifted delete line key
+KEY_SEND       Shifted end key
+KEY_SEOL       Shifted clear line key
+KEY_SEXIT      Shifted exit key
+KEY_SFIND      Shifted find key
+KEY_SHELP      Shifted help key
+KEY_SHOME      Shifted home key
+KEY_SIC        Shifted insert key
+KEY_SLEFT      Shifted left arrow key
+KEY_SMESSAGE   Shifted message key
+KEY_SMOVE      Shifted move key
+KEY_SNEXT      Shifted next object key
+KEY_SOPTIONS   Shifted options key
+KEY_SPREVIOUS  Shifted previous object key
+KEY_SPRINT     Shifted print key
+KEY_SREDO      Shifted redo key
+KEY_SREPLACE   Shifted replace key
+KEY_SRIGHT     Shifted right arrow key
+KEY_SRSUME     Shifted resume key
+KEY_SSAVE      Shifted save key
+KEY_SSUSPEND   Shifted suspend key
+KEY_SUNDO      Shifted undo key
 .TE
 .RE
 .PP
-Keypad is arranged like this:
+The keypad is arranged as follows.
 .PP
 .RS
 .TS
-allbox tab(/) ;
-c c c .
-\fBA1\fP/\fBup\fP/\fBA3\fP
-\fBleft\fP/\fBB2\fP/\fBright\fP
-\fBC1\fP/\fBdown\fP/\fBC3\fP
+allbox center;
+C C C.
+A1     up      A3
+left   B2      right
+C1     down    C3
 .TE
 .RE
 .sp
-A few of these predefined values do \fInot\fP correspond to a real key:
+Two of these symbols do
+.I not
+correspond to a real key.
 .bP
-.B KEY_RESIZE
-is returned when the \fBSIGWINCH\fP signal has been detected
-(see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X)).
-This code is returned whether or not \fBkeypad\fP has been enabled.
+.B \%wgetch
+returns
+.B \%KEY_RESIZE
+(even if the window's keypad mode is disabled)
+when
+.I \%ncurses
+detects the
+.B \%SIGWINCH
+signal;
+see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X).
 .bP
-.B KEY_MOUSE
-is returned for mouse-events (see \fBcurs_mouse\fP(3X)).
-This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
-because
-(e.g.,
-with \fBxterm\fP(1) mouse prototocol)
-\fI\%ncurses\fP must read escape sequences,
-just like a function key.
+.B \%wgetch
+returns
+.B \%KEY_MOUSE
+to indicate that a mouse event is pending collection;
+see \fBcurs_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),
+.I \%ncurses
+must read an escape sequence,
+as with a function key.
 .SS "Testing Key Codes"
 The \fBhas_key\fP routine takes a key-code value from the above list, and
 returns \fBTRUE\fP or \fBFALSE\fP according to whether
-- 
2.30.2

signature.asc
Description: PGP signature