[PATCH 23/43] man/curs_kernel.3x: Revise "RETURN VALUE" section.

[G. Branden Robinson]

Content:
* Note curs_set()'s exceptional return value convention.
* Document mvcur() failure mode.
* Drop mention of X/Open Curses's lack of error condition specification.
  (This is better sited in "PORTABILITY", and is already present there.)
* Clarify failure modes of {def,reset}_{shell,prog}_mode().

Style:
* Protect function names from hyphenation.
* Align phrasing with other recently edited ncurses man pages.
* Favor saying "ncurses" over "this implementation".

Markup:
* Break input lines after commas.
* 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_kernel.3x | 47 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x
index 1234e67bf..d00d27366 100644
--- a/man/curs_kernel.3x
+++ b/man/curs_kernel.3x
@@ -245,22 +245,45 @@ .SS ripoffline
 \fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or
 \fBnewterm\fP.
 .SH RETURN VALUE
-Except for \fBcurs_set\fP, these routines always return \fBOK\fP.
+Except for
+.BR \%curs_set ","
+these functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+.B \%curs_set
+returns the previous cursor visibility,
+and returns
+.B ERR
+if the terminal type does not support the requested
+.IR visibility "."
+.PP
+.B \%napms
+always succeeds.
 .PP
-\fBcurs_set\fP
-returns the previous cursor state, or \fBERR\fP if the
-requested \fIvisibility\fP is not supported.
+.B \%mvcur
+fails if the position
+.RI ( newrow ,
+.IR newcol )
+is outside the screen boundaries.
 .PP
-X/Open defines no error conditions.
-In this implementation
-.TP 5
-\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, 
\fBreset_shell_mode\fP
+In
+.IR \%ncurses ","
+.bP
+.BR \%def_prog_mode ","
+.BR \%def_shell_mode ","
+.BR \%reset_prog_mode ","
+and
+.B \%reset_shell_mode
 return
 .B ERR
-if the terminal was not initialized, or
-if the I/O call to obtain the terminal settings fails.
-.TP 5
-\fBripoffline\fP
+if the terminal was not initialized,
+or if the operating system's function for obtaining terminal settings
+fails.
+.bP
+.B \%ripoffline
 returns
 .B ERR
 if the maximum number of ripped-off lines
-- 
2.30.2

signature.asc
Description: PGP signature