[PATCH 10/32] man/curs_getyx.3x: Revise.

[G. Branden Robinson]

Content:
* Add cross reference to subwin(3X).
* Reassure (the many) users of `stdscr` that `getbegyx()` is
  well-behaved.

Style:
* Segregate `getparyx` from the other 3 macros in SYNOPSIS and
  DESCRIPTION sections, since it is of less general applicability.
* Recast language.  Avoid Latin abbreviations.

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 from there to gather names for man page aliases).
---
 man/curs_getyx.3x | 131 +++++++++++++++++++++++++++++++---------------
 1 file changed, 89 insertions(+), 42 deletions(-)

diff --git a/man/curs_getyx.3x b/man/curs_getyx.3x
index eadcecef2..00e77e3d8 100644
--- a/man/curs_getyx.3x
+++ b/man/curs_getyx.3x
@@ -51,62 +51,109 @@ .SH SYNOPSIS
 \fB#include <curses.h>
 .PP
 \fBvoid getyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
-\fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
 \fBvoid getbegyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
 \fBvoid getmaxyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+\fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
 .fi
 .SH DESCRIPTION
-The \fB\%getyx\fP macro places the current cursor position
-of the given window in the two integer variables \fIy\fP and \fIx\fP.
-.PP
-If \fIwin\fP is a subwindow, the \fB\%getparyx\fP macro places the beginning
-coordinates of the subwindow relative to the parent window into two integer
-variables \fIy\fP and \fIx\fP.
-Otherwise, \fB\-1\fP is placed into \fIy\fP and \fIx\fP.
+These macros obtain the cursor position and bounds information of a
+.I curses
+window
+.IR win "."
+.B \%getyx
+stores
+.IR win "'s"
+cursor position in the variables
+.I y
+and
+.IR x "."
+.B \%getmaxyx
+stores
+.IR win "'s"
+maximum valid row and column numbers in
+.I y
+and
+.IR x ","
+respectively.
+.B \%getbegyx
+similarly stores the position of
+.IR win "'s"
+origin relative to that of the screen
+(for
+.BR stdscr ","
+these coordinates are always
+.BR 0 ")."
 .PP
-Like \fB\%getyx\fP, the \fB\%getbegyx\fP and \fB\%getmaxyx\fP macros store
-the current beginning coordinates and size of the specified window.
+If
+.I win
+is a subwindow
+(see \fB\%subwin\fP(3X)),
+the
+.B \%getparyx
+macro places the coordinates of its origin relative to its parent window
+into
+.I y
+and
+.IR x ","
+and
+.B \-1
+into both if it is not.
 .SH RETURN VALUE
-The return values of these macros are undefined (i.e.,
-they should not be used as the right-hand side of assignment statements).
+No return values are defined for macros.
+Do not use them as the right-hand side of assignment statements.
 .SH NOTES
-All of these interfaces are macros.
-A \*(``&\*('' is not necessary before the variables \fIy\fP and \fIx\fP.
+All of these interfaces are implemented as macros.
+An \*(``&\*('' operator is not necessary before the variables
+.I y
+and
+.IR x "."
 .SH PORTABILITY
-The
-\fB\%getyx\fP,
-\fB\%getparyx\fP,
-\fB\%getbegyx\fP and
-\fB\%getmaxyx\fP
-macros are described in X/Open Curses, Issue 4.
+These macros are described in X/Open Curses,
+Issue 4.
 .PP
-This implementation also provides functions
-\fB\%getbegx\fP,
-\fB\%getbegy\fP,
-\fB\%getcurx\fP,
-\fB\%getcury\fP,
-\fB\%getmaxx\fP,
-\fB\%getmaxy\fP,
-\fB\%getparx\fP and
-\fB\%getpary\fP
-for compatibility with older versions of \fIcurses\fP;
+.I \%ncurses
+also provides functions
+.BR \%getbegx ","
+.BR \%getbegy ","
+.BR \%getcurx ","
+.BR \%getcury ","
+.BR \%getmaxx ","
+.BR \%getmaxy ","
+.BR \%getparx ","
+and
+.B \%getpary
+for compatibility with older versions of
+.IR curses ";"
 see \fB\%curs_legacy\fP(3X).
 .PP
-Although X/Open Curses does not address this,
-many implementations provide members of the \fB\%WINDOW\fP structure
-containing values corresponding to these macros.
-For best portability, do not rely on using the data in \fB\%WINDOW\fP,
-since some implementations make \fB\%WINDOW\fP opaque (do not allow
-direct use of its members).
+Although X/Open Curses does not address the issue,
+many implementations expose members of the
+.I \%WINDOW
+structure containing values corresponding to these macros.
+Do not rely on their availability;
+some implementations make
+.I \%WINDOW
+opaque
+(that is,
+they do not allow direct access to its members).
 .PP
 Besides the problem of opaque structures,
-the data stored in like-named members may not have like-values in
-different implementations.
-For example, the \fB\%WINDOW._maxx\fP and \fB\%WINDOW._maxy\fP values
-in \fI\%ncurses\fP have
-(at least since release 1.8.1)
+the data stored in like-named members may not have values of the same
+meaning different implementations.
+For example,
+the values of
+.B \%WINDOW._maxx
+and
+.B \%WINDOW._maxy
+in
+.I \%ncurses
+have long
+.\" (at least since its initial release, 1.8.1)
 differed by one from some other implementations.
-The difference is hidden by means of the macro \fB\%getmaxyx\fP.
+The
+.B \%getmaxyx
+macro hides this difference.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_legacy\fP(3X),
-- 
2.30.2

signature.asc
Description: PGP signature