[PATCH 20/22] man/curs_scr_dump.3x: Revise.

[G. Branden Robinson]

Content:
* Stop characterizing terminal state and properties as problems with the
  validity of a screen dump file.
* Explain why `scr_init()` would cancel a screen update based on
  terminal state and properties.
* Add a use case for `scr_init()`.
* Clarify use case for `scr_set()`.
* Add "HISTORY" section.
* Add "SEE ALSO" cross reference to terminfo(5) since specific terminal
  capabilities are discussed.

Style:
* Put a space after pointer stars in function synopses.
* Favor active voice over passive.
* Favor saying "ncurses" over "this implementation".
* Parallelize wording of "RETURN VALUE", "NOTES", and "PORTABILITY"
  sections with that of other recently edited ncurses man pages.

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.
* Annotate an anomaly of SVID 4 documentation.
---
 man/curs_scr_dump.3x | 142 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 105 insertions(+), 37 deletions(-)

diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x
index 1c4934b93..651ab931f 100644
--- a/man/curs_scr_dump.3x
+++ b/man/curs_scr_dump.3x
@@ -54,10 +54,10 @@ .SH SYNOPSIS
 .nf
 \fB#include <curses.h>
 .PP
-\fBint scr_dump(const char *\fIfilename\fP);
-\fBint scr_restore(const char *\fIfilename\fP);
-\fBint scr_init(const char *\fIfilename\fP);
-\fBint scr_set(const char *\fIfilename\fP);
+\fBint scr_dump(const char * \fIfilename\fP);
+\fBint scr_restore(const char * \fIfilename\fP);
+\fBint scr_init(const char * \fIfilename\fP);
+\fBint scr_set(const char * \fIfilename\fP);
 .fi
 .SH DESCRIPTION
 .I curses
@@ -70,83 +70,151 @@ .SH DESCRIPTION
 \fB\%putwin\fP(3X),
 respectively.
 .SS scr_dump
-\fB\%scr_dump\fP writes to
+.B \%scr_dump
+writes to
 .I filename
 the contents of the virtual screen;
 see \fB\%curscr\fP(3X).
 .SS scr_restore
-\fB\%scr_restore\fP updates the virtual screen to contain the contents
-of
+.B \%scr_restore
+updates the virtual screen to match the contents of
 .I filename
-(if it was validly written with \fB\%scr_dump\fP).
-No refresh is performed;
-after performing any further desired updates,
+(if validly written with
+.BR \%scr_dump ")."
+.I curses
+does not perform a refresh;
+after making any desired changes,
 call \fB\%doupdate\fP(3X) or similar.
 .SS scr_init
-\fB\%scr_init\fP reads
-.IR filename ,
+.B \%scr_init
+reads
+.IR filename ","
 using it to initialize
 .I curses
 data structures describing the state of the terminal screen.
-If these data are valid,
 .I curses
+then,
+if it decides the terminal state is valid,
 bases its next update of the screen on this information rather than
 clearing it and starting from scratch.
 .PP
-The data fail the validity check
+.I curses
+regards the terminal being in an invalid state for computation of
+updates based on the contents of
+.I filename
+if
 .bP
-if the terminal employs
+the terminal type supports the
 .I \%term\%info
 capabilities
 .B \%exit_ca_mode
 .RB \%( rmcup )
 or
 .B \%non_rev_rmcup
-.RB \%( nrrmc )
-are defined,
+.RB \%( nrrmc ),
 or
 .bP
-if
 .I curses
 knows that the terminal has been written to since the preceding
-\fB\%scr_dump\fP call.
+.B \%scr_dump
+call.
+.PP
+Either of the foregoing conditions means that
+.I curses
+cannot assume that the terminal's contents
+match their representation in
+.IR filename "."
+The former is due to terminal features
+(such as \fI\%xterm\fP(1)'s \*(``alternate screen\*('')
+that couple cursor-positioning mode with a local cache of screen
+contents.
+.I curses
+cannot know whether terminal is displaying from that local cache at the
+time the application calls
+.BR \%scr_init ","
+so it makes a pessimistic assumption that a full redraw is required;
+see subsection \*(``Cursor Motions\*('' of \fB\%terminfo\fP(5).
 .PP
-\fB\%scr_init\fP could be used after \fB\%initscr\fP(3X) or
-\fB\%system\fP(3) to share the screen with another process that has
-done a \fBscr_dump\fP after \fB\%endwin\fP(3X).
+.B \%scr_init
+could be used after \fB\%initscr\fP(3X) or \fI\%system\fP(3) to share
+the screen with another process that has done a
+.B \%scr_dump
+after \fB\%endwin\fP(3X).
+An application that supports suspending its state on exit and subsequent
+resumption upon later execution might use
+.B \%scr_dump
+and
+.B \%scr_init
+thus.
 .SS scr_set
-The \fBscr_set\fP routine is a combination of \fBscr_restore\fP and
-\fBscr_init\fP.  It tells the program that the information in \fIfilename\fP is
-what is currently on the screen, and also what the program wants on the screen.
-This can be thought of as a screen inheritance function.
+.B \%scr_set
+combines
+.B \%scr_restore
+and
+.BR \%scr_init ","
+synchronizing the contents of
+.I filename
+with the virtual screen.
+It can be regarded as a screen inheritance function;
+consider a real-time screen-sharing application.
 .SH RETURN VALUE
-These functions return \fBOK\fP on success and \fBERR\fP on failure.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-X/Open defines no failure conditions.
-In this implementation,
-each function fails if it cannot open
-.IR filename .
+In
+.IR \%ncurses ","
+each function returns
+.B ERR
+if it cannot open
+.IR filename "."
+.BR \%scr_init ","
+.BR \%scr_restore ","
+and
+.B \%scr_set
+return
+.B ERR
+if the contents of
+.I filename
+are invalid.
 .SH NOTES
-\fB\%scr_init\fP,
-\fB\%scr_set\fP,
+.BR \%scr_init ","
+.BR \%scr_restore ","
 and
-\fB\%scr_restore\fP may be macros.
+.B \%scr_set
+may be implemented as macros.
 .SH PORTABILITY
 X/Open Curses,
 Issue 4 describes these functions.
+It specifies no error conditions for them.
+.\" Unusually, SVID 4 explicitly indicated "OK" as a possible return
+.\" value, rather than the "integer other than ERR" refrain (p. 529).
 .PP
 .\" SVID 4, p. 529
 SVr4 omitted the
 .I \%const
 qualifiers.
 .PP
-SVr4 documentation describes \fB\%scr_init\fP such that the dump data is
-also considered invalid \*(``if the time-stamp of the tty is old\*(''
+SVr4 documentation describes
+.B \%scr_init
+such that the dump data is also considered invalid
+\*(``if the time-stamp of the tty is old\*(''
 but does not define \*(``old\*(''.
+.SH HISTORY
+SVr3 (1987) introduced
+.BR \%scr_dump ","
+.BR \%scr_init ","
+and
+.BR \%scr_restore "."
+SVr3.1 added
+.BR \%scr_set "."
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_initscr\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_util\fP(3X),
 \fB\%system\fP(3),
-\fB\%scr_dump\fP(5)
+\fB\%scr_dump\fP(5),
+\fB\%terminfo\fP(5)
-- 
2.30.2

signature.asc
Description: PGP signature