[PATCH 17/30] man/curs_inwstr.3x: Revise.

[G. Branden Robinson]

Sync with revised content of man/curs_inwstr.3x.

Content:
* Reorganize list of function synopses, grouping them by the common
  4-tuple described in ncurses.3x; a given ncurses function often has
  four variants, with a prefix that is empty, "w", "mv", or "mvw".  The
  w-prefixed function is the elementary one (the others are macros).
* Discuss elementary function `winwstr()` first in "DESCRIPTION"
  section.  Then describe how `winnwstr()` differs.  Refer the reader to
  ncurses(3X) for the variants.
* Relocate material about what X/Open Curses specifies from "RETURN
  VALUE" section to "PORTABILITY" section.
* Refer to null pointers as argument values by language literal, not
  concept.
* Relocate material about function behavior from "NOTES" section
  to "DESCRIPTION" section.
* Add "EXTENSIONS" section describing ncurses's treatment of "-1" as a
  length in `winnstr()` and its variants.
* Advise "NCURSES_VERSION" usage in "PORTABILITY" section when
  exercising ncurses extensions.
* Document a weirdness of the X/Open Curses spec for `winnstr()` and its
  variants that makes detection of wide string truncation harder for the
  application programmer.
* Improve "SEE ALSO" section.
  - Add paragraph cross referencing to non-wide counterpart function man
    pages, explicitly identifying it as such, to aid users reading about
    the "wrong" API.
  - Drop cross references to (non-wide) curs_inch.3x, curs_inchstr.3x,
    and curs_instr.3x man pages.
  - Add cross reference to curs_in_wch.3x man page.

Style:
* Put a space after pointer stars in function synopses.
* Favor active voice over passive.
* Favor saying "ncurses" over "this implementation".
* Don't refer to a function's modification of its arguments (those
  passed by reference) as "returning" them.  (X/Open Curses didn't do
  this, but Solaris 2.3 did, more evidence that it may be the origin of
  ncurses's "uncopyrighted" [sic] man pages[1].)
* Parallelize wording of "RETURN VALUE", "NOTES", and "PORTABILITY"
  sections with that of other recently edited ncurses man pages.
* Protect function names from hyphenation.

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).
* Quote punctuation-only second arguments to `BR` and `IR` macros, to
  avoid false positives reported by one of Thomas Dickey's
  style-checking scripts, per his communication.

[1] https://invisible-island.net/ncurses/ncurses-license.html#ncurses_1_8_5
---
 man/curs_inwstr.3x | 215 +++++++++++++++++++++++++++++++++------------
 1 file changed, 157 insertions(+), 58 deletions(-)

diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x
index 9bafe85db..72d3f124f 100644
--- a/man/curs_inwstr.3x
+++ b/man/curs_inwstr.3x
@@ -57,48 +57,96 @@ .SH SYNOPSIS
 .nf
 \fB#include <curses.h>
 .PP
-\fBint inwstr(wchar_t *\fIwstr\fP);
-\fBint innwstr(wchar_t *\fIwstr\fP, int \fIn\fP);
-\fBint winwstr(WINDOW *\fIwin\fP, wchar_t *\fIwstr\fP);
-\fBint winnwstr(WINDOW *\fIwin\fP, wchar_t *\fIwstr\fP, int \fIn\fP);
+\fBint inwstr(wchar_t *\ \fIwstr\fP);
+\fBint winwstr(WINDOW *\ \fIwin\fP, wchar_t *\ \fIwstr\fP);
+\fBint mvinwstr(int \fIy\fP, int \fIx\fP, wchar_t *\ \fIwstr\fP);
+\fBint mvwinwstr(WINDOW *\ \fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t *\ 
\fIwstr\fP);
 .PP
-\fBint mvinwstr(int \fIy\fP, int \fIx\fP, wchar_t *\fIwstr\fP);
-\fBint mvinnwstr(int \fIy\fP, int \fIx\fP, wchar_t *\fIwstr\fP, int \fIn\fP);
-\fBint mvwinwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t 
*\fIwstr\fP);
-\fBint mvwinnwstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t 
*\fIwstr\fP, int \fIn\fP);
+\fBint innwstr(wchar_t *\ \fIwstr\fP, int \fIn\fP);
+\fBint winnwstr(WINDOW *\ \fIwin\fP, wchar_t *\ \fIwstr\fP, int \fIn\fP);
+\fBint mvinnwstr(int \fIy\fP, int \fIx\fP, wchar_t *\ \fIwstr\fP, int \fIn\fP);
+\fBint mvwinnwstr(WINDOW *\ \fIwin\fP, int \fIy\fP, int \fIx\fP, wchar_t *\ 
\fIwstr\fP, int \fIn\fP);
 .fi
 .SH DESCRIPTION
-These routines return a string of \fBwchar_t\fP wide characters in \fIwstr\fP,
-starting at the current cursor position in the named window.
-.PP
-The four functions with \fIn\fP as the last argument return
-a leading substring at most \fIn\fP characters long
-(exclusive of the trailing NUL).
-Transfer stops at the end of the current line, or when \fIn\fP characters have
-been stored at the location referenced by \fIwstr\fP.
-.PP
-If the size \fIn\fP is not large enough to store a complete complex character,
-an error is generated.
+.B \%winwstr
+extracts a wide-character string from a
+.I curses
+window
+.IR win ","
+starting at the cursor and stopping at the end of the line,
+and stores it in
+.IR wstr ","
+terminating it with a wide null character
+and
+omitting any attributes and color pair identifier
+that
+.I curses
+associates with each character.
+.B \%winnwstr
+does the same,
+but copies at most
+.I n
+characters from
+.IR win "."
+An
+.I n
+of
+.B \-1
+implies no limit;
+.B \%winnwstr
+then works like
+.BR \%winwstr "."
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .SH RETURN VALUE
-All routines return
-\fBERR\fP
+.BR \%inwstr ","
+.BR \%winwstr ","
+.BR \%mvinwstr ","
+and
+.B \%mvwinwstr
+return
+.B OK
+on successful operation.
+.BR \%innwstr ","
+.BR \%winnwstr ","
+.BR \%mvinnwstr ","
+and
+.B \%mvwinnwstr
+return the count of wide characters copied from
+.I win
+to
+.IR wstr "."
+All return
+.B ERR
 upon failure.
-Upon
-successful completion, the *\fBinwstr\fP
-routines return
-\fBOK\fP, and the *\fBinnwstr\fP
-routines return the
-number of characters read into the string.
+.BR \%innwstr ","
+.BR \%winnwstr ","
+.BR \%mvinnwstr ","
+and
+.B \%mvwinnwstr
+return
+.B ERR
+if
+.I n
+is insufficiently large to store a complete wide character string.
+(Recall that a
+.I curses
+complex character can contain multiple wide characters,
+some of which may be non-spacing.)
 .PP
-X/Open defines no error conditions.
-This implementation returns
+In
+.IR \%ncurses ","
+they return
 .B ERR
+if
 .bP
-if the \fIwin\fP parameter is null or
-.bP
-if the \fIwstr\fP parameter is null, or
+.I win
+is
+.B NULL
+or
 .bP
-if no characters could be read.
+.I wstr
+is
+.BR NULL "."
 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
@@ -106,37 +154,88 @@ .SH RETURN VALUE
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-All routines except
-\fBwinnwstr\fP
-may be macros.
-.PP
-Each cell in the window holds a complex character
-(a spacing character and zero or more non-spacing characters)
-together with attributes and color.
-These functions store only the wide characters,
-ignoring attributes and color.
-Use \fBin_wchstr\fP to return the complex characters from a window.
+All of these functions except
+.B \%winnwstr
+may be implemented as macros.
 .PP
 Reading a line that overflows the array pointed to by
-\fIwstr\fP
+.I str
 with
-\fBinwstr\fP,
-\fBmvinwstr\fP,
-\fBmvwinwstr\fP
+.BR \%inwstr ","
+.BR \%winwstr ","
+.BR \%mvinwstr ","
 or
-\fBwinwstr\fP
+.B \%mvwinwstr
 causes undefined results.
-Therefore, the use of
-\fBinnwstr\fP,
-\fBmvinnwstr\fP,
-\fBmvwinnwstr\fP, or
-\fBwinnwstr\fP
-is recommended.
+Use of
+.BR \%innwstr ","
+.BR \%winnwstr ","
+.BR \%mvinnwstr ","
+and
+.B \%mvwinnwstr
+is recommended instead.
+.PP
+Unlike
+.BR \%instr ","
+.BR \%winstr ","
+.BR \%mvinstr ","
+and
+.BR \%mvwinstr ","
+the wide-character functions
+.BR \%inwstr ","
+.BR \%winwstr ","
+.BR \%mvinwstr ","
+and
+.B \%mvwinwstr
+return
+.B OK
+rather than a (wide) character count.
+.SH EXTENSIONS
+.BR \%innwstr ","
+.BR \%winnwstr ","
+.BR \%mvinnwstr ","
+and
+.BR \%mvwinnwstr "'s"
+treatment of
+.B \-1
+as a valid value of
+.I n
+is an
+.I \%ncurses
+extension.
 .SH PORTABILITY
-These functions are described in X/Open Curses, Issue 4.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+Notwithstanding the foregoing,
+X/Open Curses Issues 4 and 7 both state that
+.BR \%innwstr ","
+.BR \%winnwstr ","
+.BR \%mvinnwstr ","
+and
+.B \%mvwinnwstr
+\*(``fail .\|.\|. [i]f the array is not large enough to contain any
+complete characters\*(''.
+Strictly interpreted,
+this means that a caller of these functions cannot use their return
+values to detect truncation of a wide-character string copied from more
+than one character cell in
+.IR win "."
+.I \%ncurses
+reports any truncation with
+.BR ERR "."
 .SH SEE ALSO
+\fB\%curs_instr\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
 \fB\%curses\fP(3X),
-\fB\%curs_inch\fP(3X),
-\fB\%curs_inchstr\fP(3X),
-\fB\%curs_instr\fP(3X),
+\fB\%curs_in_wch\fP(3X),
 \fB\%curs_in_wchstr\fP(3X)
-- 
2.30.2

signature.asc
Description: PGP signature