[PATCH 14/17] Fix style and markup nits in "BUGS" sections.

[G. Branden Robinson]

- Use ncurses/terminfo terminology with more discipline.
- For example, say "keypad application mode" rather than "keypad bit".
- Set "ncurses", "xterm", "terminfo", and "termcap" in italics (except
  in man page cross references[1]) and protect them from hyphenation, as
  they are not English words.
- Spell "System V" with an unbreakable space.  (An _unstretchable_
  space, groff's `\~`, would be preferable, but we are still dragging
  the System V Unix troff casket.[2])
- Favor imperative mood when giving advice.
- Favor English words over Latin abbreviations.
- Favor present tense over future.
- Break long input lines.
- Break input lines after commas.

* man/curs_mouse.3x:
* man/curs_print.3x:
* man/curs_termcap.3x:
* man/curs_window.3x:
* man/infocmp.1m: Do it.

[1] However...

    https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html

[2] groff_man_style(7):

       \~        Adjustable non‐breaking space.  Use this escape
                 sequence to prevent a break inside a short phrase or
                 between a numerical quantity and its corresponding
                 unit(s).

                        Before starting the motor,
                        set the output speed to\~1.
                        There are 1,024\~bytes in 1\~KiB.
                        CSTR\~#8 documents the B\~language.

                 \~ is a GNU extension also supported by Heirloom
                 Doctools troff 050915 (September 2005), mandoc 1.9.14
                 (2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13),
                 and Plan 9 from User Space troff (commit 93f8143600,
                 2022‐08‐12), but not by Solaris or Documenter’s
                 Workbench troffs.
---
 man/curs_mouse.3x   | 39 +++++++++++++++-------------
 man/curs_print.3x   |  6 +++--
 man/curs_termcap.3x | 62 ++++++++++++++++++++++++++-------------------
 man/curs_window.3x  | 30 ++++++++++++++--------
 man/infocmp.1m      |  3 ++-
 5 files changed, 83 insertions(+), 57 deletions(-)

diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index 61f99b3d..2115e393 100644
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -382,28 +382,31 @@ .SH PORTABILITY
 wheel/scrolling mice send position reports as a sequence of
 presses of buttons 4 or 5 without matching button-releases.
 .SH BUGS
-Mouse events under xterm will not in fact be ignored during cooked mode,
-if they have been enabled by \fB\%mousemask\fP.
-Instead, the xterm mouse
-report sequence will appear in the string read.
+Mouse events from \fI\%xterm\fP are \fInot\fP ignored in cooked mode if
+they have been enabled by \fB\%mousemask\fP.
+Instead,
+the \fI\%xterm\fP mouse report sequence appear in the string read.
 .PP
-Mouse events under xterm will not be detected correctly in a window with
-its keypad bit off, since they are interpreted as a variety of function key.
-Your terminfo description should have \fB\%kmous\fP set to \*(``\eE[M\*(''
-(the beginning of the response from xterm for mouse clicks).
-Other values for \fB\%kmous\fP are permitted,
-but under the same assumption,
-i.e., it is the beginning of the response.
+Mouse event reports from \fI\%xterm\fP are not detected correctly in
+a window with keypad application mode disabled,
+since they are interpreted as a variety of function key.
+Set the the terminal's \fI\%terminfo\fP capability \fB\%kmous\fP to
+\*(``\eE[M\*(''
+(the beginning of the response from \fI\%xterm\fP for mouse clicks).
+Other values of \fB\%kmous\fP are permitted under the same assumption,
+that is,
+the report begins with that sequence.
 .PP
-Because there are no standard terminal responses that would serve to identify
-terminals which support the xterm mouse protocol, \fIncurses\fP assumes that
-if \fB\%kmous\fP is defined in the terminal description,
-or if the terminal description's primary name or aliases
-contain the string \*(``xterm\*('',
+Because there are no standard response sequences that serve to identify
+terminals supporting the \fI\%xterm\fP mouse protocol,
+\fI\%ncurses\fP assumes that if \fB\%kmous\fP is defined in the terminal
+description,
+or if the terminal type's primary name or aliases contain the string
+\%\*(``xterm\*('',
 then the terminal may send mouse events.
 The \fB\%kmous\fP capability is checked first,
-allowing the use of newer xterm mouse protocols
-such as xterm's private mode 1006.
+allowing use of newer \fI\%xterm\fP mouse protocols such as its private
+mode 1006.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_inopts\fP(3X),
diff --git a/man/curs_print.3x b/man/curs_print.3x
index 72c15a80..1271be28 100644
--- a/man/curs_print.3x
+++ b/man/curs_print.3x
@@ -71,7 +71,9 @@ .SH PORTABILITY
 It is recommended that any code depending on \fIncurses\fP extensions
 be conditioned using \fB\%NCURSES_VERSION\fP.
 .SH BUGS
-Padding in the \fBmc5p\fP, \fBmc4\fP and \fBmc5\fP capabilities will not be
-interpreted.
+Padding in the
+\fBmc5p\fP,
+\fBmc4\fP, and
+\fBmc5\fP capabilities is not interpreted.
 .SH SEE ALSO
 \fB\%curses\fP(3X)
diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index cfca2b98..8c1b5b7c 100644
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -344,38 +344,48 @@ .SS Other Compatibility
 which must be taken into account by programs which can work with all
 termcap library interfaces.
 .SH BUGS
-If you call \fBtgetstr\fP to fetch \fBca\fP or any other parameterized string,
-be aware that it will be returned in terminfo notation, not the older and
-not-quite-compatible termcap notation.
-This will not cause problems if all
-you do with it is call \fBtgoto\fP or \fBtparm\fP, which both expand
-terminfo-style strings as terminfo.
-(The \fBtgoto\fP function, if configured to support termcap, will check
-if the string is indeed terminfo-style by looking for "%p" parameters or
-"$<..>" delays, and invoke a termcap-style parser if the string does not
-appear to be terminfo).
+If you call \fB\%tgetstr\fP to fetch \fB\%ca\fP or any other
+parameterized string capability,
+be aware that it is returned in \fI\%terminfo\fP notation,
+not the older and not-quite-compatible \fI\%termcap\fP notation.
+This does not cause problems if all you do with it is call \fB\%tgoto\fP
+or \fB\%tparm\fP, which both expand
+\fI\%terminfo\fP-style strings as \fI\%terminfo\fP does.
+(The \fB\%tgoto\fP function,
+if configured to support \fI\%termcap,\fP
+checks if the string is indeed \fI\%terminfo\fP-style by looking for
+\*(``\fB%p\fP\*('' parameters or \*(``\fB<\fP.\|.\|.\fB>\fP\*('' delays,
+and invokes a \fI\%termcap\fP-style parser if the string appears not to
+use \fI\%terminfo\fP syntax.)
 .PP
-Because terminfo conventions for representing padding in string capabilities
-differ from termcap's,
-users can be surprised:
-.bP
-\fBtputs("50")\fP in a terminfo system will put out a literal \*(``50\*(''
+Because \fI\%terminfo\fP's syntax for padding in string capabilities
+differs from \fI\%termcap\fP's,
+users can be surprised.
+.IP \(bu 4
+\fB\%tputs("50")\fP in a \fI\%terminfo\fP system transmits \*(``50\*(''
 rather than busy-waiting for 50 milliseconds.
-.bP
-However, if ncurses is configured to support termcap,
-it may also have been configured to support the BSD-style padding.
+.IP \(bu 4
+However,
+if \fI\%ncurses\fP is configured to support \fI\%termcap\fP,
+it may also have been configured to support BSD-style padding.
 .IP
-In that case, \fBtputs\fP inspects strings passed to it,
+In that case,
+\fB\%tputs\fP inspects strings passed to it,
 looking for digits at the beginning of the string.
 .IP
-\fBtputs("50")\fP in a termcap system may wait for 50 milliseconds
-rather than put out a literal \*(``50\*(''
+\fB\%tputs("50")\fP in a \fI\%termcap\fP system may busy-wait for 50
+milliseconds rather than transmitting \*(``50\*(''.
 .PP
-Note that termcap has nothing analogous to terminfo's \fBsgr\fP string.
-One consequence of this is that termcap applications assume \fBme\fP
-(terminfo \fBsgr0\fP) does not reset the alternate character set.
-This implementation checks for, and modifies the data shown to the
-termcap interface to accommodate termcap's limitation in this respect.
+\fI\%termcap\fP has nothing analogous to \fI\%terminfo\fP's \fBsgr\fP
+string.
+One consequence is that \fI\%termcap\fP applications assume that
+\fBme\fP
+(equivalent to \fI\%terminfo\fP's \fBsgr0\fP capability)
+does not reset the alternate character set.
+\fI\%ncurses\fP checks for,
+and modifies the data shared with,
+the \fI\%termcap\fP interface to accommodate the latter's limitation in
+this respect.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%putc\fP(3),
diff --git a/man/curs_window.3x b/man/curs_window.3x
index 61fcbd9f..e15f1d08 100644
--- a/man/curs_window.3x
+++ b/man/curs_window.3x
@@ -241,17 +241,27 @@ .SH PORTABILITY
 .br
 PDCurses follows the scheme used in Solaris X/Open curses.
 .SH BUGS
-The subwindow functions (\fBsubwin\fP, \fBderwin\fP, \fBmvderwin\fP,
-\fBwsyncup\fP, \fBwsyncdown\fP, \fBwcursyncup\fP, \fBsyncok\fP) are flaky,
-incompletely implemented, and not well tested.
+The subwindow functions
+\fB\%subwin\fP,
+\fB\%derwin\fP,
+\fB\%mvderwin\fP,
+\fB\%wsyncup\fP,
+\fB\%wsyncdown\fP,
+\fB\%wcursyncup\fP,
+and
+\fB\%syncok\fP
+are flaky,
+incompletely implemented,
+and not well tested.
 .PP
-The System V curses documentation is very unclear about what \fBwsyncup\fP
-and \fBwsyncdown\fP actually do.
-It seems to imply that they are only
-supposed to touch exactly those lines that are affected by ancestor changes.
-The language here, and the behavior of the \fBcurses\fP implementation,
-is patterned on the XPG4 curses standard.
-The weaker XPG4 spec may result in slower updates.
+System\ V's \fIcurses\fP documentation is unclear about what
+\fB\%wsyncup\fP and \fB\%wsyncdown\fP actually do.
+It seems to imply that they are supposed to touch only those lines that
+are affected by changes to a window's ancestors.
+The language here,
+and behavior of \fI\%ncurses\fP,
+is patterned on the X/Open Curses standard;
+this approach may result in slower updates.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_initscr\fP(3X),
diff --git a/man/infocmp.1m b/man/infocmp.1m
index 6e51e8fe..3309c84a 100644
--- a/man/infocmp.1m
+++ b/man/infocmp.1m
@@ -637,7 +637,8 @@ .SH AUTHOR
 .br
 Thomas E. Dickey <dickey@invisible\-island.net>
 .SH BUGS
-The \fB\-F\fP option of \fB@INFOCMP@\fP(1M) should be a \fB@TOE@\fP(1M) mode.
+The \fB\-F\fP option of \fB\%@INFOCMP@\fP(1M) should be a
+\fB\%@TOE@\fP(1M) mode.
 .SH SEE ALSO
 \fB\%@CAPTOINFO@\fP(1M),
 \fB\%@INFOTOCAP@\fP(1M),
-- 
2.30.2

signature.asc
Description: PGP signature