[PATCH 004/100] man/curs_pad.3x: Revise.

[G. Branden Robinson]

Content:
* Rename `subpad()`'s `WINDOW` argument from `orig` to `parent`.

Style:
* Use paragraph breaks to visibly group synopsized functions.
* Relocate presentation of pad concept to the "top level" of the
  discussion, immedately after the "DESCRIPTION" heading, instead of
  doing so after describing the operation of `newpad()`.
* Favor active voice over passive.
* Use cross-reference citation form for other 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).

* man/man_db.renames.in: Add `touchline()` and `touchwin()`.
---
 man/curs_pad.3x       | 150 +++++++++++++++++++++++++-----------------
 man/man_db.renames.in |   2 +
 2 files changed, 91 insertions(+), 61 deletions(-)

diff --git a/man/curs_pad.3x b/man/curs_pad.3x
index a7b4a94a0..8420e57c6 100644
--- a/man/curs_pad.3x
+++ b/man/curs_pad.3x
@@ -57,88 +57,116 @@ .SH SYNOPSIS
 \fB#include <curses.h>
 .PP
 \fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP);
-\fBWINDOW *subpad(WINDOW *\fIorig\fP, int \fInlines\fP, int \fIncols\fP,
+\fBWINDOW *subpad(WINDOW *\fIparent\fP, int \fInlines\fP, int \fIncols\fP,
       \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
+.PP
 \fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
       \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int 
\fIsmaxcol\fB);\fR
 \fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
       \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int 
\fIsmaxcol\fB);\fR
+.PP
 \fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
 \fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
 .fi
 .SH DESCRIPTION
-.SS newpad
-\fB\%newpad\fP creates and returns a pointer to a new pad data structure
-with the given number of lines,
-\fInlines\fP,
-and columns,
-\fIncols\fP.
-A pad is like a window,
+A
+.I curses
+.I pad
+is like a window,
 except that it is not restricted by the screen size,
 and is not necessarily associated with a particular part of the screen.
 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
-(as from scrolling or echoing of input)
-do not occur.
+only part of which is to be visible on the screen.
+Pads are not automatically refreshed by scrolling or input-echoing
+operations.
 .PP
-It is not valid to call \fB\%wrefresh\fP with a \fIpad\fP argument;
-call \fB\%prefresh\fP or \fB\%pnoutrefresh\fP instead.
-They require additional parameters to specify the part of the pad to be
-displayed and the location on the screen to be used for the display.
+Pads cannot be refreshed with \fB\%wrefresh\fP(3X);
+use
+.B \%prefresh
+or
+.B \%pnoutrefresh
+instead.
+.SS newpad
+\fB\%newpad\fP creates and returns a pointer to a new pad data structure
+with the given number of lines,
+.IR nlines ,
+and columns,
+.IR ncols .
 .SS subpad
-The \fB\%subpad\fP routine creates and returns a pointer to a subwindow within 
a
-pad with the given number of lines, \fInlines\fP, and columns, \fIncols\fP.
-Unlike \fB\%subwin\fP, which uses screen coordinates, the window is at position
-(\fIbegin\fR_\fIx\fB,\fR \fIbegin\fR_\fIy\fR) on the pad.
-The window is
-made in the middle of the window \fIorig\fP, so that changes made to one window
-affect both windows.
-During the use of this routine, it will often be
-necessary to call \fB\%touchwin\fP or \fB\%touchline\fP on \fIorig\fP before
-calling \fB\%prefresh\fP.
+.B \%subpad
+creates and returns a pointer to a subwindow within a pad
+with the given number of lines,
+.IR nlines ,
+and columns,
+.IR ncols .
+Unlike \fB\%subwin\fP(3X),
+which uses screen coordinates,
+the new pad is placed at position
+.RI ( begin_y ,
+.IR begin_x )
+relative to its parent.
+Thus,
+changes made to one pad can affect both.
+When operating on a subpad,
+it is often necessary to call \fB\%touchwin\fP(3X) or
+\fB\%touchline\fP(3X) on
+.I parent
+before calling
+.BR \%prefresh .
 .SS "prefresh, pnoutrefresh"
-The \fB\%prefresh\fP and \fB\%pnoutrefresh\fP routines are analogous to
-\fB\%wrefresh\fP and \fB\%wnoutrefresh\fP except that they relate to pads 
instead
-of windows.
-The additional parameters are needed to indicate what part of the
-pad and screen are involved.
+.B \%prefresh\fP
+and
+.B \%pnoutrefresh
+are analogous to \fB\%wrefresh\fP(3X) and \fB\%wnoutrefresh\fP(3X)
+except that they operate on pads rather than windows.
+They require additional parameters are needed to indicate what portions
+of the pad and screen are involved.
 .bP
-The \fIpminrow\fP and \fIpmincol\fP parameters specify the upper
-left-hand corner of the rectangle to be displayed in the pad.
+.I pminrow
+and
+.I pmincol
+specify the upper left-hand corner of a rectanglar view of the pad.
 .bP
-The \fIsminrow\fP,
-\fIsmincol\fP, \fIsmaxrow\fP, and \fIsmaxcol\fP
-parameters specify the edges of the
-rectangle to be displayed on the screen.
+.IR sminrow ,
+.IR smincol ,
+.IR smaxrow ,
+and
+.I smaxcol
+specify the vertices 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,
+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.
-Both rectangles must be entirely
-contained within their respective structures.
-Negative values of
-\fIpminrow\fP, \fIpmincol\fP, \fIsminrow\fP, or \fIsmincol\fP are treated as if
-they were zero.
+Both rectangles must be entirely contained
+within their respective structures.
+.I curses
+treats
+negative values of any of these parameters as zero.
 .SS pechochar
-The \fB\%pechochar\fP routine is functionally equivalent
-to a call to \fB\%addch\fP
-followed by a call to \fB\%refresh\fP(3X),
-a call to \fB\%waddch\fP followed by a call
-to \fB\%wrefresh\fP, or a call to \fB\%waddch\fP followed by a call to
-\fB\%prefresh\fP.
-The knowledge that only a single character is being output is
-taken into consideration and, for non-control characters, a considerable
-performance gain might be seen by using these routines instead of their
-equivalents.
-In the case of \fB\%pechochar\fP, the last location of the pad on
-the screen is reused for the arguments to \fB\%prefresh\fP.
+.B \%pechochar
+is functionally equivalent to calling \fB\%waddch\fP(3X) followed by
+.BR \%prefresh .
+It suggests to the
+.I curses
+optimizer that only a single character is being output;
+a considerable performance benefit may be thus enjoyed.
+The location of the character
+.I ch
+written to the pad is used to populate the arguments to
+.BR \%prefresh .
 .SS pecho_wchar
-The \fB\%pecho_wchar\fP function is the analogous wide-character
-form of \fB\%pechochar\fP.
-It outputs one character to a pad and immediately refreshes the pad.
-It does this by a call to \fB\%wadd_wch\fP followed by a call
-to \fB\%prefresh\fP.
+.B \%pecho_wchar\fP
+is functionally equivalent to calling \fB\%wadd_wch\fP(3X) followed by
+.BR \%prefresh .
+It suggests to the
+.I curses
+optimizer that only a single wide character is being output;
+a considerable performance benefit may be thus enjoyed.
+The location of the character
+.I wch
+written to the pad is used to populate the arguments to
+.BR \%prefresh .
 .SH RETURN VALUE
 Functions that return an integer return \fBERR\fP upon failure and
 \fBOK\fP
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 11332a87d..70733fbaa 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -249,6 +249,8 @@ subwin.3x                   subwin.3ncurses
 syncok.3x                      syncok.3ncurses
 terminfo.3x                    terminfo.3ncurses
 tigetstr.3x                    tigetstr.3ncurses
+touchline.3x                   touchline.3ncurses
+touchwin.3x                    touchwin.3ncurses
 tparm.3x                       tparm.3ncurses
 tputs.3x                       tputs.3ncurses
 unctrl.3x                      unctrl.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature