X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_pad.3x;h=afe523b4556afcfcbe1ef5416bf1f260dce43f83;hp=1b427e1002b5ca00b71e64db6f489521e8511924;hb=9da7d09296c1b625afd18567a6828d8e7ec2ee01;hpb=58552e8c761a70f8f0bd591fecdf576fa8216e3e

diff --git a/man/curs_pad.3x b/man/curs_pad.3x
index 1b427e10..afe523b4 100644
--- a/man/curs_pad.3x
+++ b/man/curs_pad.3x
@@ -26,7 +26,11 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_pad.3x,v 1.19 2017/01/07 19:25:15 tom Exp $
+.\" $Id: curs_pad.3x,v 1.24 2017/11/21 01:16:26 tom Exp $
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .TH curs_pad 3X ""
 .na
 .hy 0
@@ -68,6 +72,7 @@ Pads can be used when a large window is needed, and only a part of the
 window will be on the screen at one time.
 Automatic refreshes of pads
 (e.g., from scrolling or echoing of input) do not occur.
+.PP
 It is not
 legal to call \fBwrefresh\fR with a \fIpad\fR as an argument; the routines
 \fBprefresh\fR or \fBpnoutrefresh\fR should be called instead.
@@ -93,12 +98,15 @@ The \fBprefresh\fR and \fBpnoutrefresh\fR routines are analogous to
 of windows.
 The additional parameters are needed to indicate what part of the
 pad and screen are involved.
+.bP
 The \fIpminrow\fR and \fIpmincol\fR parameters specify the upper
 left-hand corner of the rectangle to be displayed in the pad.
+.bP
 The \fIsminrow\fR,
 \fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR
 parameters specify the edges of the
 rectangle to be displayed on the screen.
+.PP
 The lower right-hand corner of the
 rectangle to be displayed in the pad is calculated from the screen coordinates,
 since the rectangles must be the same size.
@@ -157,6 +165,73 @@ to \fBwecho_wchar\fP returns an error.
 .SH NOTES
 Note that \fBpechochar\fR may be a macro.
 .SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+BSD curses has no \fIpad\fP feature.
+.PP
+SVr2 curses (1986) provided the \fBnewpad\fP and related functions,
+documenting them in a single line each.
+SVr3 (1987) provided more extensive documentation.
+.PP
+The documentation does not explain the term \fIpad\fP.
+However, the Apollo \fIAegis\fP workstation operating system
+supported a graphical \fIpad\fP feature:
+.bP
+These graphical pads could be much larger than the computer's display.
+.bP
+The read-only output from a command could be scrolled back to inspect,
+and select text from the pad.
+.PP
+The two uses may be related.
+.PP
+The XSI Curses standard, Issue 4 describes these functions,
+without significant change from the SVr3 documentation.
+It describes no error conditions.
+The behavior of \fBsubpad\fP if the parent window is not
+a pad is undocumented,
+and is not checked by the vendor Unix implementations:
+.bP
+SVr4 curses sets a flag in the \fBWINDOW\fP structure in \fBnewpad\fP
+which tells if the window is a \fIpad\fP.
+.IP
+However, it uses this information only in
+\fBwaddch\fP (to decide if it should call \fBwrefresh\fP) and
+\fBwscrl\fP (to avoid scrolling a pad),
+and does not check in \fBwrefresh\fP to ensure that the pad
+is refreshed properly.
+.bP
+Solaris X/Open Curses checks if a window is a pad in \fBwnoutrefresh\fP,
+returning \fBERR\fP in that case.
+.IP
+However, it only sets the flag for subwindows if the parent window is a pad.
+Its \fBnewpad\fP function does not set this information.
+Consequently, the check will never fail.
+.IP
+It makes no comparable check in \fBpnoutrefresh\fP,
+though interestingly enough, a comment in the source code
+states that the lack of a check was an MKS extension.
+.bP
+NetBSD 7 curses
+sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
+using this to help with the distinction between \fBwnoutrefresh\fP
+and \fBpnoutrefresh\fP.
+.IP
+It does not check for the case where a subwindow is created in
+a pad using \fBsubwin\fP or \fBderwin\fP.
+.IP
+The \fBdupwin\fP function returns a regular window when duplicating a pad.
+Likewise, \fBgetwin\fP always returns a window, even if the saved
+data was from a pad.
+.PP
+This implementation
+.bP
+sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
+.bP
+allows a \fBsubwin\fP or \fBderwin\fP call to succeed having a pad parent by
+forcing the subwindow to be a pad,
+.bP
+checks in both \fBwnoutrefresh\fP and \fBpnoutrefresh\fP to ensure
+that pads and windows are handled distinctly, and
+.bP
+ensures that \fBdupwin\fP and \fBgetwin\fP treat
+pads versus windows consistently.
 .SH SEE ALSO
 \fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X), \fBcurs_addch\fR(3X).