[PATCH 174/177] man/curs_window.3x: Revise "RETURN VALUE" section.

[G. Branden Robinson]

Content:
* Drop mention of SVr4's loose specification of return values, to be
  resurrected in a subsequent commit.

Style:
* Recast.
* Restructure to use bulleted paragraphs instead of tagged paragraphs to
  detail error conditions.  Sort this sequence in alphabetical order.

Markup:
* Define `bP` page-local macro; we need it now.
* Protect literals from hyphenation.
* 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/curs_window.3x | 123 ++++++++++++++++++++++++++++-----------------
 1 file changed, 76 insertions(+), 47 deletions(-)

diff --git a/man/curs_window.3x b/man/curs_window.3x
index ff40f1a6b..79b50724c 100644
--- a/man/curs_window.3x
+++ b/man/curs_window.3x
@@ -29,6 +29,10 @@
 .\"
 .\" $Id: curs_window.3x,v 1.57 2024/12/28 21:51:45 tom Exp $
 .TH curs_window 3X 2024-12-28 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" 
"Library calls"
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .SH NAME
 \fB\%newwin\fP,
 \fB\%delwin\fP,
@@ -159,72 +163,97 @@ .SS wcursyncup
 ancestors of the window to reflect the current cursor position of the
 window.
 .SH RETURN VALUE
-Routines that return an integer return the integer \fBERR\fP upon failure and
-\fBOK\fP (SVr4 only specifies "an integer value other than \fBERR\fP") upon
-successful completion.
+Functions that return integers return
+.B ERR
+upon failure and
+.B OK
+upon success.
 .PP
-Routines that return pointers return
+Functions that return pointers return
 .I NULL
 on error.
 .PP
-X/Open defines no error conditions.
-In this implementation
-.TP 5
-\fBdelwin\fP
+.I \%ncurses
+defines several error conditions.
+.bP
+.B \%delwin
 returns
 .B ERR
-if the window pointer is null, or
-if the window is the parent of another window.
-.TP 5
-\fBderwin\fP
+if
+.I win
+is a null pointer,
+or if it is the parent of another window.
+.IP
+.I \%ncurses
+maintains a list of windows,
+and checks that the pointer passed to
+.B \%delwin
+is one that it created,
+returning
+.B ERR
+if it was not.
+.bP
+.B \%derwin
 returns
 .B ERR
-if the parent window pointer is null, or
-if any of its ordinates or dimensions is negative, or
-if the resulting window does not fit inside the parent window.
-.TP 5
-\fBdupwin\fP
+if
+.I orig
+is a null pointer,
+or if any of the ordinate or dimension arguments is negative,
+or if the resulting window does not fit inside the parent window.
+.bP
+.B \%dupwin
 returns
 .B ERR
-if the window pointer is null.
-.IP
-This implementation also maintains a list of windows,
-and checks that the pointer passed to \fBdelwin\fP is one that
-it created, returning an error if it was not..
-.TP 5
-\fBmvderwin\fP
+if
+.I win
+is a null pointer.
+.bP
+.B \%mvderwin
+returns
+.B ERR
+if
+.I win
+is a null pointer,
+or if any part of the window would be placed off-screen.
+.bP
+.B \%mvwin
 returns
 .B ERR
-if the window pointer is null, or
-if some part of the window would be placed off-screen.
-.TP 5
-\fBmvwin\fP
+if
+.I win
+is a null pointer,
+if
+.I win
+is a pad,
+or if any part of the window would be placed off-screen.
+.bP
+.B \%newwin
 returns
 .B ERR
-if the window pointer is null, or
-if the window is really a pad, or
-if some part of the window would be placed off-screen.
-.TP 5
-\fBnewwin\fP
-will fail if either of its beginning ordinates is negative, or
-if either the number of lines or columns is negative.
-.TP 5
-\fBsyncok\fP
+if any of its arguments is negative.
+.bP
+.B \%subwin
 returns
 .B ERR
-if the window pointer is null.
-.TP 5
-\fBsubwin\fP
+if
+.I orig
+is a null pointer,
+or if any of the ordinate or dimension arguments is negative,
+or if the resulting window does not fit inside the parent window.
+.bP
+.B \%syncok
 returns
 .B ERR
-if the parent window pointer is null, or
-if any of its ordinates or dimensions is negative, or
-if the resulting window does not fit inside the parent window.
+if
+.I win
+is a null pointer.
+.PP
+Functions that return a window pointer fail if memory allocation
+for their data structures fails.
 .PP
-The functions which return a window pointer
-may also fail if there is insufficient memory for its data structures.
-Any of these functions will fail if the screen has not been initialized,
-i.e., with \fBinitscr\fP or \fBnewterm\fP.
+All of these functions fail if the screen has not been initialized;
+see \fBinitscr\fP(3X) or \fBnewterm\fP(3X).
 .SH NOTES
 If many small changes are made to the window, the \fBwsyncup\fP option could
 degrade performance.
-- 
2.30.2

signature.asc
Description: PGP signature