bug-ncurses
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH 21/30] man/curs_kernel.3x: Revise discussion of `getsyx()` and `s


From: G. Branden Robinson
Subject: [PATCH 21/30] man/curs_kernel.3x: Revise discussion of `getsyx()` and `setsyx()`.
Date: Sat, 8 Jun 2024 07:19:14 -0500

Content:
* Promote mentions of ncurses functions not documented in this page to
  man page cross references.
* Explicitly identify `newscr` as the "virtual screen".

Style:
* Tighten wording.
* Protect man page names from hyphenation.
* Favor active voice over passive.
* Set "virtual screen" in roman, not italics; the term is not defined
  here.
* Favor present tense over future and past.

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).
* Quote punctuation-only second arguments to `BR` and `IR` macros, to
  avoid false positives reported by one of Thomas Dickey's
  style-checking scripts, per his communication.

* man/man_db.renames.in: Add rename for getyx(3X).
---
 man/curs_kernel.3x    | 81 ++++++++++++++++++++++++++++++-------------
 man/man_db.renames.in |  1 +
 2 files changed, 58 insertions(+), 24 deletions(-)

diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x
index 8c4119de6..024d37718 100644
--- a/man/curs_kernel.3x
+++ b/man/curs_kernel.3x
@@ -106,33 +106,66 @@ .SS "resetty, savetty"
 a buffer and \fBresetty\fP restores the state to what it was at the
 last call to \fBsavetty\fP.
 .SS getsyx
-The \fBgetsyx\fP routine returns the current coordinates
-of the \fIvirtual screen\fP cursor in \fIy\fP and \fIx\fP.
-If \fBleaveok\fP is currently \fBTRUE\fP, then
-\fB\-1\fP,\fB\-1\fP is returned.
-If lines have been removed from the top of the
-screen, using \fBripoffline\fP, \fIy\fP and \fIx\fP include these lines;
-therefore, \fIy\fP and \fIx\fP should be used only as arguments for
-\fBsetsyx\fP.
+.B \%getsyx
+stores the coordinates of virtual screen
+.RB \%( newscr )
+cursor in
+.I y
+and
+.IR x "."
+If
+.BR \%newscr 's
+\fB\%leaveok\fP(3X) output option is
+.BR TRUE ","
+.B \%getsyx
+stores
+.B \-1
+in both
+.I y
+and
+.IR x "."
+If lines have been removed from the top of the screen using
+.BR \%ripoffline ","
+.I y
+includes these lines;
+therefore,
+.I y
+and
+.I x
+populated by
+.B \%getsyx
+should be used only as arguments for
+.BR \%setsyx "."
 .PP
-Few applications will use this feature,
-most use \fBgetyx\fP instead.
+Few applications use this feature;
+most call \fB\%getyx\fP(3X) instead.
 .SS setsyx
-The \fBsetsyx\fP routine sets
-the \fIvirtual screen\fP cursor to \fIy\fP, \fIx\fP.
-If \fIy\fP and \fIx\fP are both \fB\-1\fP, then
-\fBleaveok\fP is set.
-The two routines \fBgetsyx\fP and \fBsetsyx\fP
-are designed to be used by a library routine, which manipulates
-\fBcurses\fP windows but does not want to change the current position
-of the program's cursor.
-The library routine would call \fBgetsyx\fP
-at the beginning, do its manipulation of its own windows, do a
-\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call
-\fBdoupdate\fP.
+.B \%setsyx
+sets the virtual screen
+.RB \%( newscr )
+cursor location to
+.RI ( y ,
+.IR x ")."
+.B "\%setsyx(\-1, \-1)"
+is equivalent to
+.BR "\%leaveok(newscr, TRUE)" "."
+.PP
+.B \%getsyx
+and
+.B \%setsyx
+are designed to be used by a function that manipulates
+.I curses
+windows but seeks to avoid changing the cursor position.
+Such a function would first call
+.BR \%getsyx ","
+modify its windows' content,
+call \fB\%wnoutrefresh\fP(3X) on them,
+call
+.BR \%setsyx ","
+then call \fB\%doupdate\fP(3X).
 .PP
-Few applications will use this feature,
-most use \fBwmove\fP instead.
+Few applications use this feature;
+most call \fB\%wmove\fP(3X) instead.
 .SS curs_set
 The \fBcurs_set\fP routine sets the cursor state to invisible,
 normal, or very visible for \fBvisibility\fP equal to \fB0\fP,
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 570a99feb..715dad113 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -205,6 +205,7 @@ getattr.3x                  getattr.3ncurses
 getcchar.3x                    getcchar.3ncurses
 getch.3x                       getch.3ncurses
 getwin.3x                      getwin.3ncurses
+getyx.3x                       getyx.3ncurses
 halfdelay.3x                   halfdelay.3ncurses
 has_key.3x                     has_key.3ncurses
 idcok.3x                       idcok.3ncurses
-- 
2.30.2

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]