[PATCH 2/3] man/curs_addch.3x: Clarify error return.

[G. Branden Robinson]

X/Open Curses specifies no error conditions, so ncurses's return of ERR
when writing to the bottom-right character cell when `scrollok()` has
been set to false should be documented as implementation-specific, as
should ncurses's handling of multibyte characters.

Also discuss `waddch()` completely before moving on to other functions.
---
 man/curs_addch.3x | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index 8aa830cec..f801e4385 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -182,27 +182,38 @@ .SS "Line Graphics"
 ACS_VLINE      |       x       vertical line
 .TE
 .SH RETURN VALUE
-All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success
-(the SVr4 manuals specify only
-\*(``an integer value other than \fBERR\fP\*('') upon successful completion,
-unless otherwise noted in the preceding routine descriptions.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+In
+.I \%ncurses,
+.B \%waddch
+returns
+.B ERR
+if it is not possible to add a complete character at the cursor
+position,
+as when conversion of a multibyte character to a byte sequence fails,
+or at least one of the resulting bytes cannot be added to the window.
+See section \*(``PORTABILITY\*('' below regarding the use of
+.B \%waddch
+with multibyte characters.
 .PP
-If it is not possible to add a complete character,
-an error is returned:
-.bP
 If \fB\%scrollok\fP(3X) is not enabled,
-writing a character at the lower right margin succeeds.
+.B \%waddch
+can successfully write a character at the bottom right location of the
+window.
 However,
-an error is returned because it is not possible to wrap to a new line.
-.bP
-If an error is detected when converting a multibyte character to a sequence
-of bytes,
-or if it is not possible to add all of the resulting bytes in the window,
-an error is returned.
+.I \%ncurses
+returns
+.B ERR
+because it is not possible to wrap to a new line.
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP, and return an error if the position is outside the window,
+or if the window pointer is null.
 .SH NOTES
 Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and
 \fBechochar\fP may be macros.
-- 
2.30.2

signature.asc
Description: PGP signature