[PATCH 125/177] man/curs_overlay.3x: Revise "RETURN VALUE" section.

[G. Branden Robinson]

Content:
* Recast to speak only of portable and ncurses-specific behavior, not
  that of other implementations.

Style:
* Use bulleted paragraphs to organize discussion of cases in error
  returns.
* Slightly recast to use more idiomatic English.  There's an EU-English
  tendency to employ "some" where an English speaker would say "any" (or
  use only an indefinite article).  A favorite example is from an old
  Debian package description of a _Moon Patrol_ arcade game clone:
  "drive some car across the moon".

Markup:
* Define page-local `bP` macro to support bulleted paragraphs.
* 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_overlay.3x | 28 ++++++++++++++++++----------
 1 file changed, 18 insertions(+), 10 deletions(-)

diff --git a/man/curs_overlay.3x b/man/curs_overlay.3x
index d8a322f00..dc071c34b 100644
--- a/man/curs_overlay.3x
+++ b/man/curs_overlay.3x
@@ -40,6 +40,10 @@
 .el   .ds '' ""
 .\}
 .
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .SH NAME
 \fB\%overlay\fP,
 \fB\%overwrite\fP,
@@ -74,18 +78,22 @@ .SS copywin
 then copying is non-destructive,
 as in \fBoverlay\fP.
 .SH RETURN VALUE
-These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
-(SVr4 specifies only
-\*(``an integer value other than \fBERR\fP\*('')
-upon successful completion.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-X/Open defines no error conditions.
-In this implementation,
-\fBcopywin\fP,
-\fBoverlay\fP and \fBoverwrite\fP return
+In
+.IR \%ncurses ,
+they return
 .B ERR
-if either of the window pointers are null, or
-if some part of the window would be placed off-screen.
+if
+.bP
+either of the window pointers are null,
+or
+.bP
+any part of the window would be placed off-screen.
 .SH NOTES
 Note that \fBoverlay\fP and \fBoverwrite\fP may be macros.
 .SH PORTABILITY
-- 
2.30.2

signature.asc
Description: PGP signature