[PATCH 20/42] man/curs_scanw.3x: Revise.

[G. Branden Robinson]

Content:
* Fix synopsis to agree in number with operation.
* Pay more attention to the w* vs. non-w* (stdscr) distinction.
* Move discussion of SVr4 documentation and X/Open specficiation from
  "RETURN VALUE" to "PORTABILITY" section.
* Add "NOTES" section explaining absence of wide-configuration
  functions.
* Refocus "PORTABILITY" section on X/Open Curses (Issues 4 and 7).
* Lightly recast.
* Drop unmotivated cross reference to curs_termcap(3X) in "SEE ALSO"
  section.

Style:
* Set non-curses topics (man pages and similar) in italics, not bold.
* Recast to wean ourselves off the term "routine".
* Set file and data type names in italics.
* Drop angle brackets from header file names.

Markup:
* Add source-referencing annotations to "HISTORY" section.
---
 man/curs_scanw.3x | 250 +++++++++++++++++++++++++++++++---------------
 1 file changed, 167 insertions(+), 83 deletions(-)

diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x
index 8ec1e3952..216850ee7 100644
--- a/man/curs_scanw.3x
+++ b/man/curs_scanw.3x
@@ -67,110 +67,194 @@ .SH SYNOPSIS
 \fBint vwscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list 
\fIvarglist\fP);
 .fi
 .SH DESCRIPTION
-The \fBscanw\fP, \fBwscanw\fP and \fBmvscanw\fP routines are analogous to
-\fBscanf\fP [see \fBscanf\fP(3)].
-The effect of these routines is as though
-\fBwgetstr\fP were called on the window, and the resulting line used as input
-for \fBsscanf\fP(3).
-Fields which do not map to a variable in the \fIfmt\fP
-field are lost.
+\fB\%scanw\fP,
+\fB\%wscanw\fP,
+\fB\%mvscanw\fP,
+and
+\fB\%mvwscanw\fP
+are analogous to \fI\%scanf\fP(3).
+In effect,
+they call \fB\%wgetstr\fP(3X) with
+.I win
+(or
+.BR \%stdscr )
+as its first argument,
+then attempt conversion of the resulting string with \fI\%vsscanf\fP(3).
+Fields in the string that do not map to a variable in the \fIfmt\fP
+parameter are discarded.
 .PP
-The \fBvwscanw\fP and \fBvw_scanw\fP routines are analogous to \fBvscanf\fP(3).
-They perform a \fBwscanw\fP using a variable argument list.
-The third argument is a \fBva_list\fP,
-a pointer to a list of arguments, as defined in \fB<stdarg.h>\fP.
+\fB\%vwscanw\fP
+and
+\fB\%vw_scanw\fP are analogous to \fI\%vscanf\fP(3),
+and perform a \fB\%wscanw\fP using a variable argument list.
+The third argument is a \fI\%va_list\fP,
+a pointer to a list of arguments,
+as defined in \fI\%stdarg.h\fP.
 .SH RETURN VALUE
-\fBvwscanw\fP returns \fBERR\fP on failure and an integer equal to the
-number of fields scanned on success.
+These functions return
+.B ERR
+upon failure and otherwise a count of successful conversions;
+this quantity may be zero.
+.PP
+In
+.I \%ncurses,
+failure occurs if \fI\%vsscanf\fP(3) returns
+\fBEOF\fP,
+or if the window pointer
+.I win
+is null.
 .PP
-Applications may use the return value from the \fBscanw\fP, \fBwscanw\fP,
-\fBmvscanw\fP and \fBmvwscanw\fP routines to determine the number of fields
-which were mapped in the call.
+Functions with a \*(``mv\*('' prefix first perform a cursor movement
+using \fB\%wmove\fP,
+and fail if the position is outside the window.
+.SH NOTES
+No wide character counterpart functions are defined by the
+\*(``wide\*(''
+.I \%ncurses
+configuration nor by any standard.
+They are unnecessary:
+to retrieve and convert a wide-character string from a
+.I curses
+terminal keyboard,
+use these functions with the \fI\%scanf\fP(3) conversions \*(``%lc\*(''
+and \*(``%ls\*('' for wide characters and strings,
+respectively.
 .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.
+.I \%ncurses
+implements \fI\%vsscanf\fP(3) internally if it is unavailable when the
+library is configured.
 .SH PORTABILITY
-In this implementation, \fBvw_scanw\fP and \fBvwscanw\fP are equivalent,
-to support legacy applications.
-However, the latter (\fBvwscanw\fP) is obsolete:
-.bP
-The XSI Curses standard, Issue 4 described these functions,
-noting that the function
-\fBvwscanw\fP is marked TO BE WITHDRAWN, and is to be replaced by a function
-\fBvw_scanw\fP using the \fB<stdarg.h>\fP interface.
+X/Open Curses, Issue 4, describes these functions.
+It specifies no error conditions for them.
+.PP
+.I \%ncurses
+defines \fB\%vw_scanw\fP and \fB\%vwscanw\fP identically to support
+legacy applications.
+However,
+the latter is obsolete.
 .bP
-The Single Unix Specification, Version 2 states that
-\fBvw_scanw\fP  is preferred to \fBvwscanw\fP since the latter requires
-including \fB<varargs.h>\fP, which
-cannot be used in the same file as \fB<stdarg.h>\fP.
-This implementation uses \fB<stdarg.h>\fP for both, because that header
-is included in \fB<curses.h\fP>.
+X/Open Curses, Issue 4, Version 2 (1996),
+marked \fB\%vwscanw\fP as requiring \fI\%varargs.h\fP and
+\*(``TO BE WITHDRAWN\*('',
+and specified \fB\%vw_scanw\fP using the \fI\%stdarg.h\fP interface.
+.\" SUSv2 (1997) simply incorporated X/Open Curses, Issue 4, Version 2.
+.\" .bP
+.\" SUSv2 prefers \fB\%vw_scanw\fP to \fB\%vwscanw\fP;
+.\" \fI\%varargs.h\fP and \fI\%stdarg.h\fP cannot be used in the same
+.\" code.
+.\" .\" XXX: previously "same file" (presumably "translation unit" was
+.\" .\" meant), but aren't there linkage hazards?
+.\" This implementation uses \fI\%stdarg.h\fP for both,
+.\" because \fI\%curses.h\fP includes it.
 .bP
-X/Open Curses, Issue 5 (December 2007) marked \fBvwscanw\fP (along with
-\fBvwprintw\fP and the termcap interface) as withdrawn.
-.LP
-Both XSI and The Single Unix Specification, Version 2 state that these
-functions return \fBERR\fP or \fBOK\fP.
+.\" I can't find any record of X/Open Curses, Issue 5 (December 2007)
+.\" online.  See, e.g., https://www.opengroup.org/certifications/unix/\
+.\"   standards --GBR
+.\" X/Open Curses, Issue 5 (December 2007)
+X/Open Curses, Issue 7 (2009)
+marked \fB\%vwprintw\fP
+(along with \fB\%vwscanw\fP and the \fI\%termcap\fP interface)
+as withdrawn.
+.PP
+X/Open Curses Issues 4 and 7 both state that these functions return
+\fBERR\fP or \fBOK\fP.
+This is likely an erratum.
 .bP
-Since the underlying \fBscanf\fP(3) can return the number of items scanned,
-and the SVr4 code was documented to use this feature,
-this is probably an editing error which was introduced in XSI,
-rather than being done intentionally.
+Since the underlying \fI\%scanf\fP(3) returns the number of successful
+conversions,
+and SVr4
+.I curses
+was documented to use this feature,
+this may have been an editorial solecism introduced by X/Open,
+rather than an intentional change.
 .bP
-This implementation returns the number of items scanned,
-for compatibility with SVr4 curses.
-As of 2018, NetBSD curses also returns the number of items scanned.
-Both \fI\%ncurses\fP and NetBSD curses call \fBvsscanf\fP to scan the
-string,
+This implementation retains compatibility with SVr4
+.I curses.
+As of 2018,
+NetBSD
+.I curses
+also returns the number of successful conversions.
+Both
+.I \%ncurses\fP
+and NetBSD
+.I curses
+call \fI\%vsscanf\fP(3) to scan the string,
 which returns \fBEOF\fP on error.
 .bP
-Portable applications should only test if the return value is \fBERR\fP,
-since the \fBOK\fP value (zero) is likely to be misleading.
+Portable applications should test only if the return value is \fBERR\fP,
+and not compare it to \fBOK\fP,
+since that value (zero) might be misleading.
 .IP
-One possible way to get useful results would be to use a "%n" conversion
-at the end of the format string to ensure that something was processed.
+One portable way to get useful results would be to use a \*(``%n\*(''
+conversion at the end of the format string,
+and check the value of the corresponding variable to determine how many
+conversions succeeded.
 .SH HISTORY
-While \fBscanw\fP was implemented in 4BSD,
-none of the BSD releases used it until 4.4BSD (in a game).
-That early version of curses was before the ANSI C standard.
-It did not use <varargs.h>, though that was available.
-In 1991 (a couple of years after SVr4 was generally available,
+\fB\%scanw\fP was implemented in 4BSD
+(November 1980);
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\"  libcurses/scanw.c
+that early version of
+.I curses
+preceded the ANSI C standard of 1989.
+The function was unused in Berkeley distributions for over ten years,
+until 4.4BSD,
+which employed it in a game.
+The 4BSD \fB\%scanw\fP did not use \fI\%varargs.h\fP,
+though that had been available since Seventh Edition Unix (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+.\"  varargs.h
+In 1991
+(a couple of years after SVr4 was generally available,
 and after the C standard was published),
 other developers updated the library,
-using <stdarg.h> internally in 4.4BSD curses.
+using \fI\%stdarg.h\fP internally in 4.4BSD
+.I curses.
 Even with this improvement,
-BSD curses did not use function prototypes (or even declare
-functions) in the <curses.h> header until 1992.
+BSD
+.I curses
+did not use function prototypes
+(nor even declare functions)
+in \fI\%curses.h\fP until 1992.
 .PP
-SVr2 documented
-\fBscanw\fP,
-\fBwscanw\fP
-tersely as \*(``scanf through \fIstdscr\fP\*('' and
-tersely as \*(``scanf through \fIwin\fP\*('', respectively.
+SVr2 (1984) documented \fB\%scanw\fP and \fB\%wscanw\fP tersely as
+\*(``scanf through \fB\%stdscr\fP\*('' and
+\*(``scanf through \fIwin\fP\*('',
+respectively.
 .PP
-SVr3 added
-\fBmvscanw\fP, and
-\fBmvwscanw\fP, with a three-line summary saying that they were analogous
-to \fBscanf\fP(3),
-explaining that the string which would be output from \fBscanf\fP(3) would
-instead be output using \fBwaddstr\fP on the given window.
-SVr3 also added \fBvwscanw\fP, saying that the third parameter
-is a \fBva_list\fP, defined in <varargs.h>,
-and referring the reader to the manual pages for \fIvarargs\fP and
-\fBvprintf\fP for detailed descriptions.
-(Because the SVr3 documentation does not mention \fBvscanf\fP,
-that reference to \fBvprintf\fP may not be an error).
+.\" SVr3 added
+.\" \fB\%mvscanw\fP, and
+.\" \fB\%mvwscanw\fP, with a three-line summary saying that they were analogous
+.\" to \fB\%scanf\fP(3),
+.\" explaining that the string which would be output from \fB\%scanf\fP(3) 
would
+.\" instead be output using \fB\%waddstr\fP on the given window.
+.\" XXX: The above appears to be been copy-and-paste damage from
+.\" curs_printw.3x.  What did SVr3 _really_ say?  --GBR
+SVr3 (1987) added \fB\%mvscanw\fP and \fB\%mvwscanw\fP,
+with a three-line summary asserting that they were analogous to
+\fI\%scanf\fP(3),
+explaining that the string that \fI\%scanf\fP(3) would read from the
+standard input stream would instead be collected using \fB\%wgetstr\fP
+from the given window. \" XXX: Is that true? --GBR
+SVr3 also implemented \fB\%vwscanw\fP,
+describing its third parameter as a \fI\%va_list\fP,
+defined in \fI\%varargs.h\fP,
+and referred the reader to the manual pages for \fI\%varargs\fP and
+\fI\%vprintf\fP for detailed descriptions.
+(Because the SVr3 documentation does not mention \fI\%vscanf\fP,
+the reference to \fI\%vprintf\fP might not be an error).
 .PP
-SVr4 added no new variations of \fBscanw\fP,
-but provided for using <varargs.h> or <stdarg.h> to define the \fBva_list\fP
-type.
+SVr4 (1989) introduced no new variations of \fI\%scanw\fP,
+but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to
+define the \fI\%va_list\fP type.
+.\" XXX: What was the nature of this provision?  A #define?
 .PP
-X/Open Curses added \fBvw_scanw\fP to replace \fBvwscanw\fP,
-stating that its \fBva_list\fP definition requires <stdarg.h>.
+X/Open Curses, Issue 4 (1995),
+defined \fI\%vw_scanw\fP to replace \fI\%vwscanw\fP,
+stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_getstr\fP(3X),
 \fB\%curs_printw\fP(3X),
-\fB\%curs_termcap\fP(3X),
-\fB\%scanf\fP(3)
+\fB\%scanf\fP(3),
+\fB\%vscanf\fP(3)
-- 
2.30.2

signature.asc
Description: PGP signature