[PATCH 49/52] man/curs_inopts.3x: Fix style and markup nits.

[G. Branden Robinson]

Content:
* Migrate terminology: "tty" -> "terminal".
* Convert `keyname` and `define_key` to man page cross references.

Style:
* Use commas to separate function names in subsection headings, for
  consistency with man/curs_bkgd.3x, man/curs_bkgrnd.3x,
  man/curs_inopts.3x, man/curs_kernel.3x, man/curs_overlay.3x,
  man/curs_pad.3x, man/curs_termattrs.3x, and man/curs_variables.3x.
* Drop unnecessary comma.
* Set "FILE" data type name in italics, not roman.
* Center the table.
* Adjust tag widths in tagged paragraphs.
* Protect "@TIC@" expansion from automatic hyphenation.
* Lightly recast.

Markup:
* Break input lines after commas and semicolons and around multi-word
  parentheticals (except where examples of function calls are inlined).
* Use tbl(1) column modifiers to specify boldface in table heading
  rather than *roff font selection escape sequences in the table data.
* Favor man(7) font macros over *roff font escape sequences, except for
  (actual or potential) man page cross references.
---
 man/curs_inopts.3x | 427 ++++++++++++++++++++++++++++-----------------
 1 file changed, 266 insertions(+), 161 deletions(-)

diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x
index 55fef8745..39635429b 100644
--- a/man/curs_inopts.3x
+++ b/man/curs_inopts.3x
@@ -103,175 +103,243 @@ .SH SYNOPSIS
 \fBint is_raw(void);
 .fi
 .SH DESCRIPTION
-The \fI\%ncurses\fP library provides several functions which let an
-application change the way input from the terminal is handled.
-Some are global, applying to all windows.
+.I \%ncurses
+provides several functions that let an application change the way input
+from the terminal is handled.
+Some are global,
+applying to all windows.
 Others apply only to a specific window.
 Window-specific settings are not automatically applied to new or derived
 windows.
-An application must apply these to each window, if the same behavior
-is needed.
+An application must apply these to each window if the same behavior is
+desired.
 .\"
-.SS cbreak/nocbreak
-Normally, the tty driver buffers typed characters until a newline or carriage
+.SS "cbreak, nocbreak"
+Normally,
+the terminal driver buffers typed characters until a newline or carriage
 return is typed.
 The \fB\%cbreak\fP routine disables line buffering and
-erase/kill character-processing (interrupt and flow control characters are
-unaffected), making characters typed by the user immediately available to the
+erase/kill character-processing
+(interrupt and flow control characters are unaffected),
+making characters typed by the user immediately available to the
 program.
 The \fB\%nocbreak\fP routine returns the terminal to normal (cooked)
 mode.
 .PP
-Initially the terminal may or may not be in \fB\%cbreak\fP mode, as the mode is
-inherited; therefore, a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP
-explicitly.
-Most interactive programs using \fIcurses\fP set the \fB\%cbreak\fP
-mode.
+Initially the terminal may or may not be in \fB\%cbreak\fP mode,
+as the mode is inherited;
+therefore,
+a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP explicitly.
+Most interactive programs using
+.I curses
+set the \fB\%cbreak\fP mode.
 Note that \fB\%cbreak\fP overrides \fBraw\fP.
-[See \fB\%curs_getch\fP(3X) for a
-discussion of how these routines interact with \fBecho\fP and \fB\%noecho\fP.]
+[See \fB\%curs_getch\fP(3X) for a discussion of how these routines
+interact with \fBecho\fP and \fB\%noecho\fP.]
 .\"
-.SS echo/noecho
-The \fBecho\fP and \fB\%noecho\fP routines control whether characters typed by
-the user are echoed by \fB\%getch\fP(3X) as they are typed.
-Echoing by the tty
-driver is always disabled, but initially \fB\%getch\fP is in echo mode, so
-characters typed are echoed.
+.SS "echo, noecho"
+The \fBecho\fP and \fB\%noecho\fP routines control whether characters
+typed by the user are echoed by \fB\%getch\fP(3X) as they are typed.
+Echoing by the terminal driver is always disabled,
+but initially \fB\%getch\fP is in echo mode,
+so characters typed are echoed.
 Authors of most interactive programs prefer to do
-their own echoing in a controlled area of the screen, or not to echo at all, so
-they disable echoing by calling \fB\%noecho\fP.
+their own echoing in a controlled area of the screen,
+or not to echo at all,
+so they disable echoing by calling \fB\%noecho\fP.
 [See \fB\%curs_getch\fP(3X) for a
 discussion of how these routines interact with \fB\%cbreak\fP and
 \fB\%nocbreak\fP.]
 .\"
 .SS halfdelay
-The \fB\%halfdelay\fP routine is used for half-delay mode, which is similar to
-\fB\%cbreak\fP mode in that characters typed by the user are immediately
-available to the program.
-However, after blocking for \fItenths\fP tenths of
-seconds, \fBERR\fP is returned if nothing has been typed.
-The value of \fItenths\fP
-must be a number between 1 and 255.
-Use \fB\%nocbreak\fP to leave half-delay
-mode.
+The \fB\%halfdelay\fP routine is used for half-delay mode,
+which is similar to \fB\%cbreak\fP mode in that characters typed by the
+user are immediately available to the program.
+However,
+after blocking for \fItenths\fP tenths of seconds,
+\fBERR\fP is returned if nothing has been typed.
+The value of \fItenths\fP must be a number between 1 and 255.
+Use \fB\%nocbreak\fP to leave half-delay mode.
 .\"
 .SS intrflush
-If the \fB\%intrflush\fP option is enabled (\fIbf\fP is \fBTRUE\fP), and an
-interrupt key is pressed on the keyboard (interrupt, break, quit), all output 
in
-the tty driver queue will be flushed, giving the effect of faster response to
-the interrupt, but causing \fIcurses\fP to have the wrong idea of what is on
-the screen.
-Disabling the option (\fIbf\fP is \fBFALSE\fP) prevents the
-flush.
-The default for the option is inherited from the tty driver settings.
-The window argument is ignored.
+If the \fB\%intrflush\fP option is enabled
+.RI ( bf
+is
+.BR TRUE ),
+and an interrupt key is pressed on the keyboard
+(interrupt,
+break,
+quit),
+all output in the terminal driver queue is flushed,
+giving the effect of faster response to the interrupt,
+but causing
+.I curses
+to have the wrong idea of what is on the screen.
+Disabling the option
+.RI ( bf
+is
+.BR FALSE ),
+prevents the flush.
+The default for the option is inherited from the terminal driver
+settings.
+The
+.I win
+argument is ignored.
 .\"
 .SS keypad
 The \fB\%keypad\fP option enables the keypad of the user's terminal.
 If
-enabled (\fIbf\fP is \fBTRUE\fP), the user can press a function key
-(such as an arrow key) and \fB\%wgetch\fP(3X) returns a single value
-representing the function key, as in \fB\%KEY_LEFT\fP.
+enabled
+.RI ( bf
+is
+.BR TRUE ),
+the user can press a function key
+(such as an arrow key)
+and \fB\%wgetch\fP(3X) returns a single value representing the function
+key,
+as in \fB\%KEY_LEFT\fP.
 If disabled
-(\fIbf\fP is \fBFALSE\fP), \fIcurses\fP does not treat function keys
-specially and the program has to interpret the escape sequences
-itself.
-If the keypad in the terminal can be turned on (made to
-transmit) and off (made to work locally), turning on this option
-causes the terminal keypad to be turned on when \fB\%wgetch\fP(3X) is
-called.
+(\fIbf\fP is \fBFALSE\fP),
+.I curses
+does not treat function keys specially and the program has to interpret
+the escape sequences itself.
+If the keypad in the terminal can be turned on
+(made to transmit)
+and off
+(made to work locally),
+turning on this option causes the terminal keypad to be turned on when
+\fB\%wgetch\fP(3X) is called.
 The default value for keypad is \fBFALSE\fP.
 .\"
 .SS meta
-Initially, whether the terminal returns 7 or 8 significant bits on
-input depends on the control mode of the tty driver [see \fB\%termios\fP(3)].
-To force 8 bits to be returned, invoke \fBmeta\fP(\fIwin\fP,
-\fBTRUE\fP); this is equivalent, under POSIX, to setting the CS8 flag
-on the terminal.
-To force 7 bits to be returned, invoke
-\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); this is equivalent, under POSIX,
+Initially,
+whether the terminal returns 7 or 8 significant bits on input depends on
+the control mode of the terminal driver [see \fI\%termios\fP(3)].
+To force 8 bits to be returned,
+invoke
+\fBmeta\fP(\fIwin\fP, \fBTRUE\fP);
+this is equivalent,
+under POSIX,
+to setting the CS8 flag on the terminal.
+To force 7 bits to be returned,
+invoke
+\fBmeta\fP(\fIwin\fP, \fBFALSE\fP);
+this is equivalent,
+under POSIX,
 to setting the CS7 flag on the terminal.
 The window argument,
-\fIwin\fP, is always ignored.
-If the terminfo capabilities \fBsmm\fP
-(meta_on) and \fBrmm\fP (meta_off) are defined for the terminal,
-\fBsmm\fP is sent to the terminal when \fBmeta\fP(\fIwin\fP,
-\fBTRUE\fP) is called and \fBrmm\fP is sent when \fBmeta\fP(\fIwin\fP,
-\fBFALSE\fP) is called.
+.I win,
+is always ignored.
+If the terminfo capabilities
+\fBsmm\fP (meta_on) and
+\fBrmm\fP (meta_off) are defined for the terminal,
+\fBsmm\fP is sent to the terminal when
+\fBmeta\fP(\fIwin\fP, \fBTRUE\fP)
+is called and \fBrmm\fP is sent when
+\fBmeta\fP(\fIwin\fP, \fBFALSE\fP) is called.
 .\"
-.SS nl/nonl
-The \fBnl\fP and \fBnonl\fP routines control whether the underlying display
-device translates the return key into newline on input.
+.SS "nl, nonl"
+The \fBnl\fP and \fBnonl\fP routines control whether the underlying
+display device translates the return key into newline on input.
 .\"
 .SS nodelay
-The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking call.
-If no input is ready, \fB\%getch\fP returns \fBERR\fP.
+The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking
+call.
+If no input is ready,
+\fB\%getch\fP returns \fBERR\fP.
 If disabled
-(\fIbf\fP is \fBFALSE\fP), \fB\%getch\fP waits until a key is pressed.
+.RI ( bf
+is
+.BR FALSE ),
+\fB\%getch\fP waits until a key is pressed.
 .SS notimeout
-When interpreting an escape sequence, \fB\%wgetch\fP(3X) sets a timer
+When interpreting an escape sequence,
+\fB\%wgetch\fP(3X) sets a timer
 while waiting for the next character.
-If \fB\%notimeout(\fIwin\fR,
-\fBTRUE\fP) is called, then \fB\%wgetch\fP does not set a timer.
-The
-purpose of the timeout is to differentiate between sequences received
-from a function key and those typed by a user.
+If
+\fB\%notimeout(\fIwin\fR, \fBTRUE\fP)
+is called,
+then \fB\%wgetch\fP does not set a timer.
+The purpose of the timeout is to distinguish sequences produced by a
+function key from those typed by a user.
 .\"
-.SS raw/noraw
-The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out of raw
-mode.
-Raw mode is similar to \fB\%cbreak\fP mode, in that characters typed are
-immediately passed through to the user program.
-The differences are that in
-raw mode, the interrupt, quit, suspend, and flow control characters are all
-passed through uninterpreted, instead of generating a signal.
-The behavior of
-the BREAK key depends on other bits in the tty driver that are not set by
-\fIcurses\fP.
+.SS "raw, noraw"
+The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out
+of raw mode.
+Raw mode is similar to \fB\%cbreak\fP mode,
+in that characters typed are immediately passed through to the user
+program.
+The differences are that in raw mode,
+the interrupt,
+quit,
+suspend,
+and flow control characters are all
+passed through uninterpreted,
+instead of generating a signal.
+The behavior of the BREAK key depends on other bits in the terminal
+driver that are not set by
+.I curses.
 .\"
-.SS qiflush/noqiflush
-When the \fB\%noqiflush\fP routine is used, normal flush of input and
-output queues associated with the \fBINTR\fP, \fBQUIT\fP and
-\fBSUSP\fP characters will not be done [see \fB\%termios\fP(3)].
+.SS "qiflush, nqiflush"
+When the \fB\%noqiflush\fP routine is used,
+normal flush of input and output queues associated with the \fBINTR\fP,
+\fBQUIT\fP and \fBSUSP\fP characters will not be done
+[see \fB\%termios\fP(3)].
 When
-\fB\%qiflush\fP is called, the queues will be flushed when these control
-characters are read.
-You may want to call \fB\%noqiflush\fP in a signal
-handler if you want output to continue as though the interrupt
-had not occurred, after the handler exits.
+\fB\%qiflush\fP is called,
+the queues will be flushed when these control characters are read.
+You may want to call \fB\%noqiflush\fP in a signal handler if you want
+output to continue as though the interrupt had not occurred,
+after the handler exits.
 .\"
-.SS timeout/wtimeout
+.SS "timeout, wtimeout"
 The \fB\%timeout\fP and \fB\%wtimeout\fP routines set blocking or
 non-blocking read for a given window.
 If \fIdelay\fP is negative,
-blocking read is used (i.e., waits indefinitely for
-input).
-If \fIdelay\fP is zero, then non-blocking read is used
-(i.e., read returns \fBERR\fP if no input is waiting).
+a blocking read is used
+(i.e.,
+waits indefinitely for input).
+If \fIdelay\fP is zero,
+then a non-blocking read is used
+(i.e.,
+.I read
+returns \fBERR\fP if no input is waiting).
 If
-\fIdelay\fP is positive, then read blocks for \fIdelay\fP
-milliseconds, and returns \fBERR\fP if there is still no input.
-Hence, these routines provide the same functionality as \fB\%nodelay\fP,
+\fIdelay\fP is positive,
+then
+.I read
+blocks for \fIdelay\fP milliseconds,
+and returns \fBERR\fP if there is still no input.
+Hence,
+these routines provide the same functionality as \fB\%nodelay\fP,
 plus the additional capability of being able to block for only
-\fIdelay\fP milliseconds (where \fIdelay\fP is positive).
+\fIdelay\fP milliseconds
+(where \fIdelay\fP is positive).
 .\"
 .SS typeahead
-The \fIcurses\fP library does \*(``line-breakout optimization\*(''
-by looking for typeahead periodically while updating the screen.
-If input is found, and it is coming from a tty,
+.I curses
+does \*(``line-breakout optimization\*('' by looking for typeahead
+periodically while updating the screen.
+If input is found,
+and it is coming from a terminal,
 the current update is postponed until
 \fB\%refresh\fP(3X) or \fB\%doupdate\fP is called again.
 This allows faster response to commands typed in advance.
-Normally, the input FILE
-pointer passed to \fB\%newterm\fP, or \fBstdin\fP in the case that
-\fB\%initscr\fP was used, will be used to do this typeahead checking.
+Normally,
+the input
+.I FILE
+pointer passed to \fB\%newterm\fP,
+or \fBstdin\fP in the case that \fB\%initscr\fP was used,
+will be used to do this typeahead checking.
 The \fB\%typeahead\fP routine specifies that the file descriptor
 \fIfd\fP is to be used to check for typeahead instead.
 If \fIfd\fP is
-\-1, then no typeahead checking is done.
+\-1,
+then no typeahead checking is done.
 .\"
 .SH RETURN VALUE
-All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
+All routines that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
 (SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
 upon successful completion,
 unless otherwise noted in the preceding routine descriptions.
@@ -279,7 +347,8 @@ .SH RETURN VALUE
 X/Open does not define any error conditions.
 In this implementation,
 functions with a window parameter will return an error if it is null.
-Any function will also return an error if the terminal was not initialized.
+Any function will also return an error if the terminal was not
+initialized.
 Also,
 .RS 3
 .TP 5
@@ -304,18 +373,23 @@ .SH NOTES
 \fB\%wtimeout\fP
 may be implemented as macros.
 .PP
-The \fB\%noraw\fP and \fB\%nocbreak\fP calls follow historical practice in that
-they attempt to restore to normal (\*(``cooked\*('') mode
+\fB\%noraw\fP and \fB\%nocbreak\fP follow historical practice in that
+they attempt to restore normal (\*(``cooked\*('') mode
 from raw and cbreak modes respectively.
-Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver
-control states that are hard to predict or understand; it is not recommended.
+Mixing \fBraw\fP/\fB\%noraw\fP and \fB\%cbreak\fP/\fB\%nocbreak\fP calls
+leads to terminal driver control states that are hard to predict or
+understand;
+doing so is not recommended.
 .SH EXTENSIONS
-This implementation provides four functions which may be used to detect
-if the corresponding flags were set or reset:
+.I \%ncurses
+provides four \*(``is_\*('' functions that may be used to detect if the
+corresponding flags were set or reset.
 .PP
 .TS
-l l l.
-\fBQuery\fP    \fBSet\fP       \fBReset\fP
+center;
+Lb Lb Lb
+L  L  L .
+Query  Set     Reset
 _
 is_cbreak      cbreak  nocbreak
 is_echo        echo    noecho
@@ -323,16 +397,18 @@ .SH EXTENSIONS
 is_raw raw     noraw
 .TE
 .PP
-In each case, the function returns
-.TP 5
+In each case,
+the function returns
+.TP 4 \" "-1" + 2n
 1
 if the flag is set,
-.TP 5
+.TP
 0
-if the flag is reset, or
-.TP 5
+if the flag is reset,
+or
+.TP
 \-1
-if the \fIcurses\fP library was not initialized.
+if the library is not initialized.
 .PP
 These routines are specific to \fI\%ncurses\fP.
 They were not supported on Version 7, BSD or System V implementations.
@@ -342,40 +418,63 @@ .SH PORTABILITY
 Except as noted in the section on extensions,
 these functions are described in the XSI Curses standard, Issue 4.
 .PP
-The \fI\%ncurses\fP library obeys the XPG4 standard
-and the historical practice of the
-AT&T \fIcurses\fP implementations,
-in that the echo bit is cleared when \fIcurses\fP
+.I \%ncurses
+follows X/Open Curses
+and the historical practice of AT&T
+.I curses
+implementations,
+in that the echo bit is cleared when
+.I curses
 initializes the terminal state.
-BSD \fIcurses\fP differed from this slightly; it
-left the echo bit on at initialization, but the BSD \fBraw\fP call turned it
-off as a side-effect.
-For best portability, set \fBecho \fPor \fB\%noecho\fP explicitly
-just after initialization, even if your program remains in cooked mode.
+BSD
+.I curses
+differed from this slightly;
+it left the echo bit on at initialization,
+but the BSD \fBraw\fP call turned it off as a side effect.
+For best portability,
+set \fBecho\fP or \fB\%noecho\fP explicitly just after initialization,
+even if your program remains in cooked mode.
 .PP
-The XSI Curses standard is ambiguous on the question of whether \fBraw\fP
-should disable the CRLF translations controlled by \fBnl\fP and \fBnonl\fP.
-BSD \fIcurses\fP did turn off these translations;
-AT&T \fIcurses\fP (at least as late as SVr1) did not.
-We chose to do so, on the theory that a programmer requesting
-raw input wants a clean (ideally 8-bit clean) connection that the operating
-system will not alter.
+X/Open Curses is ambiguous regarding whether \fBraw\fP should disable
+the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP.
+BSD
+.I curses
+did turn off these translations;
+AT&T
+.I curses
+(at least as late as SVr1)
+did not.
+.I \%ncurses
+does so,
+on the assumption that a programmer requesting raw input wants a clean
+(ideally,
+8-bit clean)
+connection that the operating system will not alter.
 .PP
 When \fB\%keypad\fP is first enabled,
-\fI\%ncurses\fP loads the key-definitions for the current terminal
-description.
+.I \%ncurses
+loads the key definitions for the current terminal description.
 If the terminal description includes extended string capabilities,
-e.g., from using the \fB\-x\fP option of \fB@TIC@\fP,
-then \fI\%ncurses\fP also defines keys for the capabilities whose names
-begin with \*(``k\*(''.
-The corresponding keycodes are generated and (depending on previous
-loads of terminal descriptions) may differ from one execution of a
-program to the next.
-The generated keycodes are recognized by the \fB\%keyname\fP function
+e.g.,
+from using the
+.B \-x
+option of \fB\%@TIC@\fP,
+then
+.I \%ncurses
+also defines keys for the capabilities whose names begin with
+\*(``k\*(''.
+The corresponding keycodes are generated and
+(depending on previous loads of terminal descriptions)
+may differ from one execution of a program to the next.
+The generated keycodes are recognized by the \fB\%keyname\fP(3X)
+function
 (which will then return a name beginning with \*(``k\*('' denoting the
 terminfo capability name rather than \*(``K\*('',
-used for \fIcurses\fP key-names).
-On the other hand, an application can use \fB\%define_key\fP to establish
+used for
+.I curses
+key names).
+On the other hand,
+an application can use \fB\%define_key\fP(3X) to establish
 a specific keycode for a given string.
 This makes it possible for an application to check for an extended
 capability's presence with \fB\%tigetstr\fP,
@@ -383,16 +482,22 @@ .SH PORTABILITY
 .PP
 Low-level applications can use \fB\%tigetstr\fP to obtain the definition
 of any particular string capability.
-Higher-level applications which use the \fIcurses\fP \fB\%wgetch\fP
-and similar functions to return keycodes rely upon the order in which
-the strings are loaded.
+Higher-level applications which use the
+.I curses
+\fB\%wgetch\fP and similar functions to return keycodes rely upon the
+order in which the strings are loaded.
 If more than one key definition has the same string value,
 then \fB\%wgetch\fP can return only one keycode.
-Most \fIcurses\fP implementations (including \fI\%ncurses\fP)
+Most
+.I curses
+implementations
+(including
+.IR \%ncurses )
 load key definitions in the order
 defined by the array of string capability names.
 The last key to be loaded determines the keycode which will be returned.
-In \fI\%ncurses\fP,
+In
+.I \%ncurses,
 you may also have extended capabilities interpreted as key definitions.
 These are loaded after the predefined keys,
 and if a capability's value is the same as a previously-loaded
-- 
2.30.2

signature.asc
Description: PGP signature