[PATCH 12/20] Revise discussion of screen dumps.

[G. Branden Robinson]

* man/curs_scr_dump.3x: Add introductory paragraph.  Cross reference
  getwin() and putwin() pages.  Protect function name literals from
  hyphenation.  Favor man(7) font style macros over *roff font selection
  escape sequences to set metasyntactic variable names.  Deitalicize
  "virtual screen" in favor of a cross reference to its defining man
  page.  Discuss terminfo capabilities using their long names as well as
  terminfo codes.  Italicize and explicitly hyphenate "terminfo".  Move
  use case for `scr_init()` from "NOTES" section to its description.
  Recast discussion of return value in line with recent revisions.  In
  "PORTABILITY", annotate functions' missing "const" qualifiers in SVr4.
  Slightly recast.

* man/man_db.renames.in: Add "getwin.3x" and "putwin.3x" renames.

* man/scr_dump.5 (SYNOPSIS): Drop section.  It communicated nothing.
  (PORTABILITY): Recast and update style.
---
 man/curs_scr_dump.3x  |  99 ++++++++++++++--------
 man/man_db.renames.in |   2 +
 man/scr_dump.5        | 188 ++++++++++++++++++++++++------------------
 3 files changed, 177 insertions(+), 112 deletions(-)

diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x
index ceb27fe0c..1b0e42aa8 100644
--- a/man/curs_scr_dump.3x
+++ b/man/curs_scr_dump.3x
@@ -60,55 +60,88 @@ .SH SYNOPSIS
 \fBint scr_set(const char *\fIfilename\fP);
 .fi
 .SH DESCRIPTION
+.I curses
+provides applications the ability to write the contents of the screen
+to a file and read them back.
+To read/write a window
+(rather than the whole screen)
+from/to a file,
+use \fB\%getwin\fP(3X) and
+\fB\%putwin\fP(3X),
+respectively.
 .SS scr_dump
-The \fBscr_dump\fP routine dumps the current contents
-of the \fIvirtual screen\fP
-to the file \fIfilename\fP.
+\fB\%scr_dump\fP writes to
+.I filename
+the contents of the virtual screen;
+see \fB\%curscr\fP(3X).
 .SS scr_restore
-The \fBscr_restore\fP routine sets the \fIvirtual screen\fP to the contents
-of \fIfilename\fP, which must have been written using \fBscr_dump\fP.
-The next call to \fBdoupdate\fP restores
-the \fIphysical screen\fP to the way it looked in the dump file.
+\fB\%scr_restore\fP updates the virtual screen to contain 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,
+call \fB\%doupdate\fP(3X) or similar.
 .SS scr_init
-The \fBscr_init\fP routine reads in the contents of \fIfilename\fP and uses
-them to initialize the \fBcurses\fP data structures about what the terminal
-currently has on its screen.
-If the data is determined to be valid,
-\fBcurses\fP bases its next update of the screen on this information rather
-than clearing the screen and starting from scratch.
-\fBscr_init\fP is used
-after \fBinitscr\fP(3X) or a \fBsystem\fP(3) call to share
-the screen with another process which has done a \fBscr_dump\fP after its
-\fBendwin\fP(3X) call.
-The data is declared invalid
+\fB\%scr_init\fP reads
+.I filename,
+using it to initialize
+.I curses
+data structures describing the state of the terminal screen.
+If these data are valid,
+.I curses
+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
 .bP
-if the terminfo capabilities \fBrmcup\fP and \fBnrrmc\fP exist, also
+if the terminal employs
+.I \%term\%info
+capabilities
+.B \%exit_ca_mode
+.RB ( \%rmcup )
+or
+.B \%non_rev_rmcup
+.RB ( \%nrrmc )
+are defined,
+or
 .bP
-if the terminal has been written to since the preceding \fBscr_dump\fP call.
+if
+.I curses
+knows that the terminal has been written to since the preceding
+\fB\%scr_dump\fP call.
+.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).
 .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.
-.PP
-To read (write) a window from (to) a file, use the \fBgetwin\fP and
-\fBputwin\fP routines [see \fBcurs_util\fP(3X)].
 .SH RETURN VALUE
-These routines return the integer \fBERR\fP upon failure and \fBOK\fP
-upon success.
+These functions return \fBOK\fP on success and \fBERR\fP on failure.
 .PP
-X/Open defines no error conditions.
+X/Open defines no failure conditions.
 In this implementation,
-each will return an error if the file cannot be opened.
+each function fails if it cannot open
+.I filename.
 .SH NOTES
-Note that \fBscr_init\fP, \fBscr_set\fP, and \fBscr_restore\fP may be macros.
+\fB\%scr_init\fP,
+\fB\%scr_set\fP,
+and
+\fB\%scr_restore\fP may be macros.
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4,
-which adds \fI\%const\fP qualifiers to the arguments.
+X/Open Curses, Issue 4, describes these functions.
+.PP
+.\" SVID 4, p. 529
+SVr4 omitted the
+.I \%const
+qualifiers.
 .PP
-The SVr4 docs merely say under \fBscr_init\fP that the dump data is also
-considered invalid \*(``if the time-stamp of the tty is old\*('' but do
-not define \*(``old\*(''.
+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\*(''
+but does not define \*(``old\*(''.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_initscr\fP(3X),
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index fe3fe6715..4ff302394 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -197,6 +197,7 @@ get_wch.3x                  get_wch.3ncurses
 getattr.3x                     getattr.3ncurses
 getcchar.3x                    getcchar.3ncurses
 getch.3x                       getch.3ncurses
+getwin.3x                      getwin.3ncurses
 has_key.3x                     has_key.3ncurses
 idcok.3x                       idcok.3ncurses
 idlok.3x                       idlok.3ncurses
@@ -218,6 +219,7 @@ newterm.3x                  newterm.3ncurses
 newwin.3x                      newwin.3ncurses
 nodelay.3x                     nodelay.3ncurses
 notimeout.3x                   notimeout.3ncurses
+putwin.3x                      putwin.3ncurses
 refresh.3x                     refresh.3ncurses
 reset_shell_mode.3x            reset_shell_mode.3ncurses
 restartterm.3x                 restartterm.3ncurses
diff --git a/man/scr_dump.5 b/man/scr_dump.5
index d976fae88..99abf6e56 100644
--- a/man/scr_dump.5
+++ b/man/scr_dump.5
@@ -47,8 +47,6 @@
 .SH NAME
 scr_dump \-
 \fIcurses\fR screen dump
-.SH SYNOPSIS
-.B scr_dump
 .SH DESCRIPTION
 The curses library provides applications with the ability to write the
 contents of a window to an external file using \fBscr_dump\fP or \fBputwin\fP,
@@ -131,51 +129,47 @@ .SS "ncurses5 (Legacy)"
 This is similar to Unix System\ V,
 but does not write a \*(``magic number\*('' to identify the file format.
 .SH PORTABILITY
-There is no standard format for \fBputwin\fP.
-This section gives a brief description of the existing formats.
+There is no standard format for
+.I curses
+screen dumps.
+A brief survey of the existing implementations follows.
 .SS "X/Open Curses"
-Refer to \fIX/Open Curses, Issue 7\fP (2009).
-.PP
-X/Open's documentation for \fIenhanced curses\fP says only:
+X/Open Curses, Issue 7 specifies little.
+It says
+(boldface emphasis added)
 .RS 3
 .PP
-The \fBgetwin(\ ) \fPfunction reads window-related data
-stored in the file by \fIputwin(\ )\fP.
-The function
-then creates and initializes a new window using that data.
+\*(``[t]he \fI\%getwin()\fP function reads window-related data stored in
+the file by \fI\%putwin()\fP.
+The function then creates and initializes a new window using that data.
 .PP
-The \fBputwin(\ )\fP function writes all data associated
-with \fIwin\fP into the \fI\%stdio\fP(3) stream to which \fIfilep\fP
-points, using an \fBunspecified format\fP.
-This information can be retrieved later using \fBgetwin(\ )\fP.
+The \fI\%putwin()\fP function writes all data associated with \fIwin\fP
+into the \fI\%stdio\fP stream to which \fIfilep\fP points,
+using an \fBunspecified format\fP.
+This information can be retrieved later using \fI\%getwin()\fP.\*(''
 .RE
 .PP
 In the mid-1990s when the X/Open Curses document was written,
-there were still systems using older, less capable curses libraries
-(aside from the BSD curses library which was not relevant to X/Open
-because it did not meet the criteria for \fIbase curses\fP).
-The document explained the term \*(``enhanced\*('' as follows:
-.RS 3
-.bP
-Shading is used to identify \fIX/Open Enhanced Curses\fP material,
-relating to interfaces included to provide enhanced capabilities
-for applications originally written to be compiled on systems
-based on the Unix operating system.
-Therefore, the features described may not be present on systems
-that conform to \fBXPG4 or to earlier XPG releases\fP.
-The relevant reference pages may provide additional
-or more specific portability warnings about use of the material.
-.RE
+there were still System\ V systems using older,
+less capable
+.I curses
+libraries.
+BSD
+.I curses
+was not relevant to X/Open because it did not meet the criteria
+for base-level conformance;
+see \fB\%ncurses\fP(3X).
 .PP
-In the foregoing, emphasis was added to \fBunspecified format\fP
-and to \fBXPG4 or to earlier XPG releases\fP,
-for clarity.
-.SS "Unix System V"
-Unix System\ V curses identified the file format by writing a
-\*(``magic number\*('' at the beginning of the dump.
+.SS "System V"
+System\ V
+.I curses
+identified the file format by writing a \*(``magic number\*('' at the
+beginning of the dump.
 The \fI\%WINDOW\fP data and the lines of text follow, all in binary form.
 .PP
-The Solaris curses source has these definitions:
+Solaris
+.I curses
+has the following definitions.
 .PP
 .RS 4
 .EX
@@ -190,9 +184,12 @@ .SS "Unix System V"
 .PP
 That is, the feature was likely introduced in SVr2 (1984),
 and improved in SVr3 (1987).
-The Solaris curses source has no magic number for SVr4 (1989).
-Other operating systems (AIX and HP-UX) use a magic number which would
-correspond to this definition:
+Solaris
+.I curses
+has no magic number for SVr4 (1989).
+Other System\ V operating systems
+(AIX and HP-UX)
+use a magic number that would correspond to the following.
 .PP
 .RS 4
 .EX
@@ -202,8 +199,8 @@ .SS "Unix System V"
 .RE
 .PP
 That octal number in bytes is 001, 035.
-Because most Unix vendors use big-endian hardware,
-the magic number is written with the high-order byte first, e.g.,
+Because most Unix vendors at the time used big-endian hardware,
+the magic number is written with the high-order byte first.
 .PP
 .RS 4
 .EX
@@ -211,16 +208,21 @@ .SS "Unix System V"
 .EE
 .RE
 .PP
-After the magic number, the \fI\%WINDOW\fP structure and line-data are
-written in binary format.
-While the magic number used by the Unix systems can be seen using \fBod\fP(1),
-none of the Unix systems documents the format used for screen-dumps.
+After the magic number,
+the \fI\%WINDOW\fP structure and line data are written in binary format.
+While the magic number used by these systems can be observed with
+\fIod\fP(1),
+none of them documents the format used for screen dumps.
 .PP
-The Unix systems do not use identical formats.
-While collecting information for for this manual page,
-the \fIsavescreen\fP test-program
-produced dumps of different size
-(all on 64-bit hardware, on 40x80 screens):
+Nor do they use an identical format,
+even with the System\ V family.
+The
+.I \%ncurses
+.I \%savescreen
+test program was used to collect information for this manual page.
+It produced dumps of different size
+(all on 64-bit hardware,
+on 40x80 screens):
 .bP
 AIX (51817 bytes)
 .bP
@@ -230,31 +232,49 @@ .SS "Unix System V"
 .bP
 \fI\%ncurses\fP5 (12888 bytes)
 .SS Solaris
-As noted above, Solaris curses has no magic number corresponding
-to SVr4 curses.
-This is odd since Solaris was the first operating system
-to pass the SVr4 guidelines.
-Solaris has two versions of curses:
+As noted above,
+Solaris
+.I curses
+has no magic number corresponding to SVr4
+.I curses.
+This is odd,
+since Solaris was the first operating system to meet the SVr4
+guidelines.
+Solaris furthermore supplies two versions of
+.I curses.
 .bP
-The default curses library uses the SVr3 magic number.
+The default
+.I curses
+library uses the SVr3 magic number.
 .bP
-There is an alternate curses library in \fB/usr/xpg4\fP.
-This uses a textual format with no magic number.
+An alternate
+.I curses
+library
+(which we term
+.I \%xcurses),
+available in
+.I /usr/xpg4,
+uses a textual format with no magic number.
 .IP
-According to the copyright notice, the \fIxpg4\fP Solaris curses library was
-developed by MKS (Mortice Kern Systems) from 1990 to 1995.
+According to its copyright notice,
+this
+.I \%xcurses
+library was developed by MKS
+(Mortice Kern Systems) from 1990 to 1995.
 .IP
-Like ncurses6, there is a file-header with parameters.
-Unlike ncurses6, the contents of the window are written piecemeal,
-with coordinates and attributes for each chunk of text rather
-than writing the whole window from top to bottom.
+Like ncurses6,
+it includes a header with parameters.
+Unlike ncurses6,
+the contents of the window are written piecemeal,
+with coordinates and attributes for each chunk of text rather than
+writing the whole window from top to bottom.
 .SS PDCurses
-PDCurses added support for screen dumps in version 2.7 (2005).
-Like Unix System\ V and ncurses5,
+.I \%PDCurses
+added support for screen dumps in version 2.7 (2005).
+Like System\ V and ncurses5,
 it writes the \fI\%WINDOW\fP structure in binary,
 but begins the file with its three-byte identifier \*(``PDC\*('',
-followed by a one-byte version,
-e.g.,
+followed by a single-byte version number.
 .PP
 .RS 4
 .EX
@@ -262,23 +282,33 @@ .SS PDCurses
 .EE
 .RE
 .SS NetBSD
-As of April 2017, NetBSD curses does
-not support \fBscr_dump\fP and \fBscr_restore\fP
-(or \fBscr_init\fP, \fBscr_set\fP),
-although it has \fBputwin\fP and \fBgetwin\fP.
+As of April 2017,
+NetBSD
+.I curses
+does not support \fB\%scr_dump\fP and \fB\%scr_restore\fP
+(or \fB\%scr_init\fP,
+\fB\%scr_set\fP),
+although it has \fB\%putwin\fP and \fB\%getwin\fP.
 .PP
-Like ncurses5, NetBSD \fBputwin\fP does not identify its dumps with a
-useful magic number.
+Like ncurses5,
+NetBSD \fB\%putwin\fP does not identify its dumps with a useful magic
+number.
 It writes
 .bP
-the curses shared library major and minor versions
-as the first two bytes (e.g., 7 and 1),
+the
+.I curses
+shared library major and minor versions as the first two bytes
+(for example,
+7 and 1),
 .bP
 followed by a binary dump of the \fI\%WINDOW\fP,
 .bP
-some data for wide-characters referenced by the \fI\%WINDOW\fP structure, and
+some data for wide characters referenced by the \fI\%WINDOW\fP
+structure,
+and
 .bP
-finally, lines as done by other implementations.
+finally,
+lines as done by other implementations.
 .SH EXAMPLES
 Given a simple program which writes text to the screen
 (and for the sake of example, limiting the screen-size to 10x20):
-- 
2.30.2

signature.asc
Description: PGP signature