[PATCH 45/45] man/curs_kernel.3x: Revise discussion of `mvcur()`.

[G. Branden Robinson]

Content:
* Add a paragraph, derived from a 2016 email of Thomas Dickey's
  motivating using of `mvcur()`, since it is mysterious to many (judging
  by the mailing list archives and its own erstwhile placement in the
  ncurses man pages).
* Add "EXTENSIONS" section, and migrate to it (from "PORTABILITY") the
  explanation of ncurses's special treatment of negative previous
  coordinate arguments.
* Quote X/Open Curses standard more accurately, and set the material as
  a block quotation.
* Drop claim that `mvcur()` is "not well specified".

Style:
* Recast.

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/curs_kernel.3x | 103 ++++++++++++++++++++++++++++-----------------
 1 file changed, 65 insertions(+), 38 deletions(-)

diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x
index dfcb5bc7f..7d09fcbaa 100644
--- a/man/curs_kernel.3x
+++ b/man/curs_kernel.3x
@@ -141,14 +141,38 @@ .SS curs_set
 the previous \fIcursor\fP state is returned;
 otherwise, \fBERR\fP is returned.
 .SS mvcur
-\fB\%mvcur\fP provides low-level cursor motion.
-It takes effect immediately
-(rather than at the next refresh).
+.B \%mvcur
+provides low-level cursor motion.
+It takes effect immediately,
+rather than at the next refresh.
 Unlike the other low-level output functions,
-which either write to the standard output or pass an output function
-parameter,
-\fB\%mvcur\fP uses an output file descriptor derived from
-the output stream parameter of \fB\%newterm\fP(3X).
+which either write to the standard output stream
+or are passed a function pointer to perform output,
+.B \%mvcur
+uses a file descriptor derived from the output stream parameter of
+\fB\%newterm\fP(3X).
+.PP
+One application of
+.B \%mvcur
+accompanies the temporary use of another program to write to the
+terminal screen.
+For example,
+first call \fB\%refresh\fP(3X) to ensure that the screen and the
+library's model of it is up to date;
+then call
+.BR \%reset_shell_mode ";"
+write to the screen with the external application;
+call
+.BR \%reset_prog_mode ";"
+and finally call
+.B \%mvcur
+to set the cursor's location to where
+.I \%curses
+thinks it is,
+since the library has no knowledge of how the external application
+moved it.
+.\" https://lists.gnu.org/archive/html/bug-ncurses/2016-10/msg00002.html
+.PP
 .SS napms
 .B \%napms
 sleeps for
@@ -222,6 +246,23 @@ .SH NOTES
 invisible or very visible.
 There is no way for \fI\%ncurses\fP to determine the initial cursor
 state to restore that.
+.SH EXTENSIONS
+In
+.IR \%ncurses ","
+.B \%mvcur
+accepts
+.B \-1
+for either or both old coordinates.
+This value tells
+.I \%ncurses
+that the old location is unknown,
+and that it must use only absolute motion,
+as with the
+.B \%cursor_address
+.RB ( cup )
+capability,
+rather than the least costly combination of absolute and relative
+motion.
 .SH PORTABILITY
 The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP
 are not described in X/Open Curses, Issue 4.
@@ -232,44 +273,30 @@ .SH PORTABILITY
 This is misleading, as they are macros with no documented semantics
 for the return value.
 .PP
-X/Open Curses notes that after calling \fB\%mvcur\fP,
-the
-.I curses
-state may not match the actual terminal state,
-and that an application should touch and refresh the window before
-resuming normal
-.I curses
-calls.
+X/Open Curses notes:
+.RS
+.PP
+\*(``After use of
+.IR \%mvcur "(),"
+the model Curses maintains of the state of the terminal might not
+match the actual state of the terminal.
+An application should touch and refresh the window before
+resuming conventional use of Curses.\*(''
+.RE
+.PP
 Both
 .I \%ncurses
 and SVr4
 .I curses
-implement \fB\%mvcur\fP using the
+implement
+.B \%mvcur
+using the
 .I SCREEN
-data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
-So though it is documented as a
-.I \%term\%info
-function,
-\fB\%mvcur\fP is really a
-.I curses
-function that is not well specified.
-.PP
+data allocated in either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X).
 X/Open Curses states that the old location must be given for
-\fB\%mvcur\fP to accommodate terminals that lack absolute cursor
-positioning.
+.B \%mvcur
+to accommodate terminals that lack absolute cursor positioning.
 .\" X/Open Curses Issue 7, p. 161
-.I \%ncurses
-allows the caller to use \-1 for either or both old coordinates.
-The \-1 tells
-.I \%ncurses
-that the old location is unknown,
-and that it must use only absolute motion,
-as with the
-.B \%cursor_address
-.RB ( cup )
-capability,
-rather than the least costly combination of absolute and relative
-motion.
 .PP
 If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP.
 That, and the limitation to 30 seconds,
-- 
2.30.2

signature.asc
Description: PGP signature