[PATCH 13/15] man/wresize.3x: Revise.

[G. Branden Robinson]

Content:
* Add parenthetical cross reference to wide-character counterpart of
  `wbkgdset()` to aid users of that API.
* Add "EXTENSIONS" section identifying this function as such.
* Advise "NCURSES_VERSION" usage in "PORTABILITY" section when
  exercising ncurses extensions.
* Reorganize material about this function's origin into a new "HISTORY"
  section from "PORTABILITY" and "AUTHORS".
* More explicitly identify Thomas Dickey as the author of the
  (unofficial) BSD curses version of this function as well.

Style:
* Recast.
* Describe operation specifically in terms of function parameters where
  possible.
* Favor active voice over passive.
* Favor present tense over future.
* Parallelize description of return value with other recent changes to
  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).
---
 man/wresize.3x | 97 ++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 78 insertions(+), 19 deletions(-)

diff --git a/man/wresize.3x b/man/wresize.3x
index 9b45885b9..1a6df64c9 100644
--- a/man/wresize.3x
+++ b/man/wresize.3x
@@ -41,32 +41,91 @@ .SH SYNOPSIS
 \fBint wresize(WINDOW * \fIwin\fP, int \fIlines\fP, int \fIcolumns\fP);
 .fi
 .SH DESCRIPTION
-This \fI\%ncurses\fP extension to standard \fIcurses\fP reallocates
-storage for a \fIcurses\fP window to adjust its dimensions to the
-specified values.
+.BR \%wresize ","
+an
+.I \%ncurses
+extension to the
+.I curses
+library,
+reallocates storage for
+.IR win ,
+adjusting its dimensions to
+.I lines
+and
+.IR columns "."
 If either dimension is larger than its current value,
-the expanded part of the window is filled with blanks merged with
-current background rendition
-(as set by \fB\%wbkgdset\fP(3X)).
+.I \%ncurses
+fills the expanded part of the window with the blank character
+configured by \fB\%wbkgdset\fP(3X)
+(wide-character API users: \fB\%wbkgrndset\fP(3X)).
 .SH RETURN VALUE
-\fB\%wresize\fP returns \fBERR\fP upon failure and \fBOK\fP on success.
-It will fail if either of the dimensions is less than or equal to zero,
-or if an error occurs while (re)allocating memory for the window.
+.B \%wresize
+returns
+.B OK
+on success and
+.B ERR
+on failure.
+It fails if either
+.I lines
+or
+.I columns
+is less than or equal to zero,
+or if an error occurs while (re)allocating memory for
+.IR win "."
 .SH NOTES
-The only restriction placed on the dimensions is that they be greater
-than zero.
-They are \fInot\fP compared to the \fIcurses\fP screen dimensions;
+The only restriction placed on the values of
+.I lines
+and
+.I columns
+is that they be greater than zero.
+They are
+.I not
+compared to the dimensions of the
+.I curses
+screen;
 this keeps the logic of \fB\%resizeterm\fP(3X) simple.
-The caller must ensure that the window's dimensions fit within the
-actual screen dimensions.
+The caller must ensure that
+.IR win 's
+dimensions fit within those of the screen.
+.SH EXTENSIONS
+.B \%wresize
+is an \fB\%ncurses\fP(3X) extension,
+and is not found in SVr4
+.IR curses ","
+4.4BSD
+.IR curses ","
+or any other previous
+.I curses
+implementation.
 .SH PORTABILITY
-It is not possible to resize windows with SVr4 \fIcurses\fP.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
 .PP
-\fI\%ncurses\fP introduced this extension in mid-1995.
-NetBSD \fIcurses\fP adopted it in 2001,
-and \fI\%PDCurses\fP in 2003.
+NetBSD
+.I curses
+adopted
+.B \%wresize
+in 2001,
+and
+.I \%PDCurses
+in 2003.
+.\" Version/release numbers would be good. --GBR
+.PP
+It is not possible to resize windows with SVr4
+.IR curses "."
+.SH HISTORY
+Thomas Dickey developed
+.B \%wresize
+as an extension to BSD
+.I curses
+in 1988,
+and brought it to
+.I \%ncurses
+in mid-1995.
 .SH AUTHORS
 Thomas Dickey
-(from an equivalent function written in 1988 for BSD \fIcurses\fP).
 .SH SEE ALSO
 \fB\%resizeterm\fP(3X)
-- 
2.30.2

signature.asc
Description: PGP signature