[PATCH 112/177] man/curs_mouse.3x: Revise "DESCRIPTION" section.

[G. Branden Robinson]

Content:
* Add introductory material.  Promote much material useful for general
  understanding from function-specific subsections to this intro.
* Promote some function mentions to man page cross references.

Style:
* Respell some formal arguments as hyphenated noun phrases since they
  are not, and need not be, C language literals.
* Favor present tense over future.

Markup:
* 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) and terms in the "NAME" section (because the
  generated edit_man.sh script expects font selection escape sequences
  when scraping terms thence to gather names for man page aliases).

* man/man_db.renames.in: Add ungetch.3x.
---
 man/curs_mouse.3x     | 328 ++++++++++++++++++++++++++++--------------
 man/man_db.renames.in |   1 +
 2 files changed, 225 insertions(+), 104 deletions(-)

diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index 54c76127f..27197a5e3 100644
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -73,55 +73,100 @@ .SH SYNOPSIS
 \fI/* functions */
 \fBbool has_mouse(void);
 .PP
-\fBmmask_t mousemask(mmask_t \fInewmask\fP, mmask_t * \fIoldmask\fP);
+\fBmmask_t mousemask(mmask_t \fInew-mask\fP, mmask_t * \fIold-mask\fP);
 .PP
 \fBint getmouse(MEVENT * \fIevent\fP);
 \fBint ungetmouse(MEVENT * \fIevent\fP);
 .PP
 \fBbool wenclose(const WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP);
 .PP
-\fBbool mouse_trafo(int * \fIpY\fP, int * \fIpX\fP, bool \fIto_screen\fP);
+\fBbool mouse_trafo(int * \fIpY\fP, int * \fIpX\fP, bool \fIto-screen\fP);
 \fBbool wmouse_trafo(const WINDOW * \fIwin\fP,
-      \fBint * \fIpY\fB, int * \fIpX\fB, bool \fIto_screen\fB);
+      \fBint * \fIpY\fB, int * \fIpX\fB, bool \fIto-screen\fB);
 .PP
 \fBint mouseinterval(int \fIerval\fB);\fR
 .fi
 .SH DESCRIPTION
-These functions provide an interface to mouse events from
-\fB\%ncurses\fP(3X).
-Mouse events are represented by \fB\%KEY_MOUSE\fP
-pseudo-key values in the \fB\%wgetch\fP(3X) input stream.
+.I \%ncurses
+provides an interface to the mouse or other pointing device.
+An application can register its interest in such events;
+the library then exposes the availability of a mouse event via an
+.IR "input character reading function" ":"
+this is \fB\%wgetch\fP(3X) in the non-wide character
+.I curses
+API and \fB\%wget_wch\fP(3X) in the wide character API.
+A queue distinct from that used for keyboard events
+accumulates the details of mouse events.
+The input character reading function
+reports the
+.B \%KEY_MOUSE
+key code when a mouse event is available for collection.
+A single mouse event queue serves all windows
+associated with the screen.
+.PP
+The
+.I \%MEVENT
+structure describes a mouse event.
+Its
+.I y
+and
+.I x
+coordinates are screen-,
+not window-,
+relative.
+The
+.I \%bstate
+member has exactly one bit set indicating the event type.
+.PP
+.I \%ncurses
+ignores mouse events when input is in canonical (\*(``cooked\*('') mode,
+and produces an error beep when canonical mode is simulated in a window
+by a function such as \fB\%getstr\fP(3X) that expects a linefeed to
+terminate its input loop.
 .SS has_mouse
-The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver
-has been successfully initialized,
-and \fBFALSE\fP otherwise.
-.PP
-Mouse events are ignored when input is in canonical (\*(``cooked\*('')
-mode, and cause an error beep when canonical mode is being simulated in
-a window by a function such as \fB\%getstr\fP that expects a linefeed
-for input-loop termination.
+The terminal type or operating system interface
+must support the encoding of mouse events.
+.B \%has_mouse
+returns
+.B TRUE
+if
+.IR \%ncurses 's
+mouse driver initialized successfully,
+and
+.B FALSE
+otherwise.
 .SS mousemask
-To make mouse events visible, use the \fB\%mousemask\fP function.
-This sets the mouse events to be reported.
-By default, no mouse events are reported.
+Use
+.B \%mousemask
+to select the varieties of mouse event your application wishes to
+receive.
+By default,
+.I \%ncurses
+reports no mouse events.
 .bP
-The function returns an updated copy of \fInewmask\fP
-to indicate which of the specified mouse events can be reported.
+The function returns an updated copy of
+.I new-mask
+indicating which of the specified mouse events can be reported.
 .IP
-If the screen has not been initialized,
-or if the terminal does not support mouse-events,
-this function returns 0.
+If the screen is not initialized,
+or the terminal interface does report mouse events,
+.B \%mousemask
+returns 0.
 .bP
-If \fIoldmask\fP is
-.RI non- NULL ","
-this function fills the indicated location with the previous value of the
-current screen's mouse event mask.
-.PP
-As a side effect, setting a zero mouse mask may turn off the mouse pointer;
+If
+.I old-mask
+is not a null pointer,
+.B \%mousemask
+stores the previous value
+of the screen's mouse event mask there.
+.PP
+As a side effect,
+setting a zero mouse mask may turn off the mouse cursor;
 setting a nonzero mask may turn it on.
 Whether this happens is device-dependent.
 .SS "Mouse Events"
-Here are the mouse event type masks which may be defined:
+Several mouse event types may be selected;
+construct a mask by logically \*(``or\*(''-ing their values.
 .PP
 .TS
 Lb Lb
@@ -159,13 +204,13 @@ .SS "Mouse Events"
 BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked
 _
 BUTTON_SHIFT   T{
-shift was down during button state change
+a shift key was down during button state change
 T}
 BUTTON_CTRL    T{
-control was down during button state change
+a control key was down during button state change
 T}
 BUTTON_ALT     T{
-alt was down during button state change
+an alt key was down during button state change
 T}
 ALL_MOUSE_EVENTS       report all button state changes
 REPORT_MOUSE_POSITION  report mouse movement
@@ -173,79 +218,150 @@ .SS "Mouse Events"
 .TE
 .SS getmouse
 Once a class of mouse events has been made visible in a window,
-calling the \fB\%wgetch\fP function on that window may return
-\fB\%KEY_MOUSE\fP as an indicator that a mouse event has been queued.
-To read the event data and pop the event off the queue, call
-\fB\%getmouse\fP.
-This function will return \fBOK\fP if a mouse event
-is actually visible in the given window, \fBERR\fP otherwise.
-When \fB\%getmouse\fP returns \fBOK\fP, the data deposited as y and
-x in the event structure coordinates will be screen-relative character-cell
-coordinates.
-The returned state mask will have exactly one bit set to
-indicate the event type.
-The corresponding data in the queue is marked invalid.
-A subsequent call to \fB\%getmouse\fP will retrieve the next older
-item from the queue.
+calling the input character reading function on that window may return
+.B \%KEY_MOUSE
+as an indicator that a mouse event is enqueued.
+To read the event data and pop the event off the queue,
+call
+.BR \%getmouse ","
+which returns
+.B OK
+if a mouse event is visible in the given window
+and
+.B ERR
+otherwise.
+When
+.B \%getmouse
+returns
+.BR OK ","
+it deposits data describing the mouse event in the
+.I event
+pointer you supply.
+A subsequent
+.B \%getmouse
+call retrieves the next older event from the queue.
 .SS ungetmouse
-The \fB\%ungetmouse\fP function behaves analogously to \fB\%ungetch\fP.
-It pushes
-a \fB\%KEY_MOUSE\fP event onto the input queue, and associates with that event
-the given state data and screen-relative character-cell coordinates.
+.B \%ungetmouse
+behaves analogously to \fB\%ungetch\fP(3X).
+It pushes a
+.B \%KEY_MOUSE
+event onto the screen's input queue,
+and
+.I event
+onto the mouse event queue.
 .SS wenclose
-The \fB\%wenclose\fP function tests whether a given pair of screen-relative
-character-cell coordinates is enclosed by a given window, returning \fBTRUE\fP
-if it is and \fBFALSE\fP otherwise.
-It is useful for determining what subset of
-the screen windows enclose the location of a mouse event.
-.PP
-If the parameter is a pad,
-\fB\%wenclose\fP uses the most recent screen coordinates used for
-this pad in
-\fB\%prefresh\fP(3X) or
-\fB\%pnoutrefresh\fP(3X).
+.B \%wenclose
+returns
+.B TRUE
+if the pair of screen-relative coordinates
+.RI ( y ,
+.IR x ")"
+is enclosed by the given window
+.IR win ","
+and
+.B FALSE
+otherwise.
+If
+.I win
+is a pad,
+.B \%wenclose
+uses its most recent screen coordinates as specified in
+a \fB\%prefresh\fP(3X) or \fB\%pnoutrefresh\fP(3X) call.
+.PP
+.B \%wenclose
+is useful for determining what subset of the screen's windows
+encloses the location of a mouse event;
+it is otherwise independent of the
+.I \%ncurses
+mouse API.
 .SS wmouse_trafo
-The \fB\%wmouse_trafo\fP function transforms a given pair of coordinates
-from \fB\%stdscr\fP-relative coordinates
-to coordinates relative to the given window or vice versa.
-The resulting \fB\%stdscr\fP-relative coordinates are not always
-identical to screen coordinates due to the mechanism to reserve
-lines on top or bottom of the screen for other purposes
-(see the \fB\%ripoffline\fP(3X) and \fB\%slk_init\fP(3X) calls, for example).
-.bP
-If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
-\fIpY, pX\fP must reference the coordinates of a location
-inside the window \fIwin\fP.
-They are converted to \fB\%stdscr\fP-relative coordinates and returned
-through the pointers.
-If the conversion was successful, the function returns \fBTRUE\fP.
-.IP
-If one of the parameters was
-.I NULL
-or the location is
-not inside the window, \fBFALSE\fP is returned.
-.bP
-If \fIto_screen\fP is
-\fBFALSE\fP, the pointers \fIpY, pX\fP must reference
-\fB\%stdscr\fP-relative coordinates.
-They are converted to window-relative coordinates if the
-window \fIwin\fP encloses this point.
-In this case the function returns \fBTRUE\fP.
-.IP
-If one of the parameters is
-.I NULL
-or the point is not inside the
-window, \fBFALSE\fP is returned.
-.PP
-The referenced coordinates
-are only replaced by the converted coordinates if the transformation was
-successful.
+.B \%wmouse_trafo
+transforms the given pair of coordinate pointers
+.RI ( pY ,
+.IR pX ")"
+from a
+.IR win -relative
+basis to a screen-relative one or
+.IR "vice versa" ","
+as
+.I to-screen
+is
+.B TRUE
+or
+.BR FALSE ","
+respectively.
+.BR \%stdscr -relative
+coordinates are not always identical to screen coordinates:
+.I curses
+supports reservation of screen lines at the top and/or bottom
+for other purposes;
+see \fB\%ripoffline\fP(3X) and \fB\%slk_init\fP(3X).
+.PP
+If
+.I to-screen is
+.B TRUE
+and the pointers
+.RI ( pY ,
+.IR pX ")"
+reference coordinates inside
+.IR win ","
+.I \%ncurses
+updates their values to
+.BR \%stdscr -relative
+coordinates and returns
+.BR TRUE "."
+If either
+.I pY
+or
+.I pX
+is a null pointer,
+or
+.RI ( pY ,
+.IR pX ")"
+is not inside
+.IR win ","
+.B \%wmouse_trafo
+returns
+.BR FALSE "."
+.PP
+If
+.I to-screen is
+.B FALSE
+and the pointers
+.RI ( pY ,
+.IR pX ")"
+reference coordinates inside
+.BR stdscr ","
+.I \%ncurses
+updates their values to
+.IR win -relative
+coordinates and returns
+.BR TRUE "."
+If either
+.I pY
+or
+.I pX
+is a null pointer,
+or
+.RI ( pY ,
+.IR pX ")"
+is not inside
+.BR stdscr ","
+.B \%wmouse_trafo
+returns
+.BR FALSE "."
 .SS mouse_trafo
-The \fB\%mouse_trafo\fP function performs the same translation
-as \fB\%wmouse_trafo\fP,
-using \fB\%stdscr\fP for \fIwin\fP.
+.B \%mouse_trafo
+applies the
+.B \%wmouse_trafo
+translation to
+.BR \%stdscr "."
+If no screen lines are reserved by \fB\%ripoffline\fP(3X) or
+\fB\%slk_init\fP(3X),
+this is the identity transformation.
 .SS mouseinterval
-The \fB\%mouseinterval\fP function sets the maximum time
+.B \%mouseinterval
+sets the maximum time
 (in thousandths of a second)
 that can elapse between press and release events for them to
 be resolved as a
@@ -256,7 +372,9 @@ .SS mouseinterval
 with motion,
 as a \*(``drag\*(''.
 .PP
-Calling \fB\%mouseinterval(0)\fP disables click resolution.
+Calling
+.B \%mouseinterval(0)
+disables click resolution.
 When
 .I \%ncurses
 detects a mouse event,
@@ -265,10 +383,12 @@ .SS mouseinterval
 with the first event.
 If the timeout expires without input activity
 (which would happen with a zero interval),
-then no click resolution will occur.
+then no click resolution occurs.
 .PP
 This function returns the previous interval value.
-Use \fB\%mouseinterval(\-1)\fP to obtain the interval without altering it.
+Use
+.B \%mouseinterval(\-1)
+to obtain the interval without altering it.
 .PP
 The mouse interval is set to one sixth of a second
 when the corresponding screen is initialized,
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 1e7d367a7..416100f9a 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -268,6 +268,7 @@ tparm.3x                    tparm.3ncurses
 tputs.3x                       tputs.3ncurses
 trace.3x                       trace.3ncurses
 unctrl.3x                      unctrl.3ncurses
+ungetch.3x                     ungetch.3ncurses
 use_default_colors.3x          use_default_colors.3ncurses
 use_env.3x                     use_env.3ncurses
 use_extended_names.3x          use_extended_names.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature