[PATCH 44/52] man/curs_mouse.3x: Relocate and recast extension/portability material.

[G. Branden Robinson]

Add new "EXTENSIONS" section, and move declaration of API extension
thither.  Move discussion of preprocessor macro and ncurses mouse
API/ABI versioning from "NOTES" to "PORTABILITY".

Explicitly note that SVr4 curses had `getmouse()` too.
---
 man/curs_mouse.3x | 58 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 37 insertions(+), 21 deletions(-)

diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index 91da8ce56..956ab6deb 100644
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -261,24 +261,6 @@ .SH RETURN VALUE
 the terminal was not initialized.
 In that case, it returns the maximum interval value (166).
 .SH NOTES
-The feature macro \fB\%NCURSES_MOUSE_VERSION\fP is provided so the preprocessor
-can be used to test whether these features are present.
-If the interface is changed, the value of \fB\%NCURSES_MOUSE_VERSION\fP will be
-incremented.
-These values for \fB\%NCURSES_MOUSE_VERSION\fP may be
-specified when configuring \fI\%ncurses\fP:
-.RS 3
-.TP 3
-1
-has definitions for reserved events.
-The mask uses 28 bits.
-.TP 3
-2
-adds definitions for button 5,
-removes the definitions for reserved events.
-The mask uses 29 bits.
-.RE
-.PP
 The order of the \fB\%MEVENT\fP structure members is not guaranteed.
 Additional fields may be added to the structure in the future.
 .PP
@@ -326,10 +308,44 @@ .SH NOTES
 For example, in xterm,
 wheel/scrolling mice send position reports as a sequence of
 presses of buttons 4 or 5 without matching button-releases.
+.SH EXTENSIONS
+These functions were designed for
+\fB\%ncurses\fP(3X),
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
+(SVr4
+.I curses
+did have a
+.I \%getmouse
+function,
+which took no argument and returned a different type.)
 .SH PORTABILITY
-These calls were designed for \fI\%ncurses\fP,
-and are not found in SVr4 \fIcurses\fP,
-4.4BSD \fIcurses\fP, or any other previous version of \fIcurses\fP.
+Applications employing the
+.I \%ncurses
+mouse extension should condition its use on the visibility of the
+.B \%NCURSES_MOUSE_VERSION
+preprocessor macro.
+When the interface changes,
+the macro's value increments.
+Multiple versions are available when
+.I \%ncurses
+is configured;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' of \fB\%ncurses\fP(3X).
+The following values may be specified.
+.RS 3
+.TP 3
+1
+has definitions for reserved events.
+The mask uses 28 bits.
+.TP 3
+2
+adds definitions for button 5,
+removes the definitions for reserved events.
+The mask uses 29 bits.
+.RE
 .PP
 SVr4 \fIcurses\fP had support for the mouse in a variant of \fBxterm\fP(1).
 It is mentioned in a few places, but with no supporting documentation:
-- 
2.30.2

signature.asc
Description: PGP signature