[PATCH 043/177] man/curs_getstr.3x: Fix content, style, and markup nits.

[G. Branden Robinson]

Content:
* Correct statement about `wgetstr()` calling `wechochar()` internally;
  it does not.  It calls `waddch()` instead.
* Revise advice regarding use of `n`-infixed functions.  They are not a
  magic bullet; the programmer must still prepare an adequately sized
  buffer to house the characters written by `wgetstr()`.
* Drop date references in "PORTABILITY" section; they are probably
  important only in the "HISTORY" section.
* Cross reference sysconf(3) man page when mentioning `LINE_MAX` symbol.
* X/Open Curses Issue 5 does not seem to formally exist.  Perhaps it
  never proceeded past the draft phase.  See the "Referenced Documents"
  section of X/Open Curses Issue 7 (PDF pp. 16-17).  Clarify this page's
  reference to it.

Style:
* Set `wgetch` as man page cross reference.

Markup:
* Add source citation to SVID 4 quotation.
---
 man/curs_getstr.3x | 49 ++++++++++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 23 deletions(-)

diff --git a/man/curs_getstr.3x b/man/curs_getstr.3x
index 4b5f0d4c6..75d034bcf 100644
--- a/man/curs_getstr.3x
+++ b/man/curs_getstr.3x
@@ -117,7 +117,7 @@ .SH DESCRIPTION
 .B \%wgetstr
 updates
 .I win
-with \fB\%wechochar\fP(3X).
+with \fB\%waddch\fP(3X).
 Further,
 .bP
 the erase character
@@ -162,9 +162,7 @@ .SH RETURN VALUE
 .IR NULL ","
 or
 .bP
-if an internal
-.B \%wgetch
-call fails.
+if an internal \fB\%wgetch\fP(3X) call fails.
 .PP
 Further,
 in
@@ -185,28 +183,28 @@ .SH NOTES
 .B \%wgetnstr
 may be implemented as macros.
 .PP
-Use of
-.BR \%getstr ","
-.BR \%mvgetstr ","
-.BR \%mvwgetstr ","
-or
-.B \%wgetstr
-to read input that
-overruns the buffer pointed to by
+Reading input that overruns the buffer pointed to by
 .I str
 causes undefined results.
-Use their
+Use the
 .BR n -infixed
-counterpart functions instead.
+functions,
+and allocate sufficient storage for
+.I str
+\(em at least
+.IR n +1
+times
+.BR sizeof(char) "."
 .PP
-While
-.B \%wgetnstr
-is conceptually a series of calls to
+While these functions conceptually implement
+a series of calls to
 .BR \%wgetch ","
-it also temporarily changes properties of the
+they also temporarily change properties of the
 .I curses
 screen to permit simple editing of the input buffer.
-It saves the screen's state and then calls \fBnl\fP(3X) and,
+Each function saves the screen's state,
+calls \fBnl\fP(3X),
+and,
 if the screen was in canonical (\*(``cooked\*('') mode,
 \fB\%cbreak\fP(3X).
 Before returning,
@@ -251,8 +249,9 @@ .SH PORTABILITY
 SVr4
 .I curses
 describes a successful return value only as
+.\" SVID 4, vol. 3, p. 495
 \*(``an integer value other than
-.IR ERR \*(''.
+.IR ERR \*(''. \" Courier roman in source
 .PP
 SVr3 and early SVr4
 .I curses
@@ -268,7 +267,7 @@ .SH PORTABILITY
 \*(``home\*('' key,
 \*(``clear\*('' key,
 .IR etc. )
-.\" SVID 4, Volume 3, p. 495
+.\" SVID 4, vol. 3, p. 495
 .RE
 .PP
 without further detail.
@@ -289,7 +288,9 @@ .SH PORTABILITY
 Version\ 2 \" p. 94 (PDF 114)
 but disappeared from Issue\ 7.) \" p. 105 (PDF 119)
 .PP
-X/Open Curses Issue\ 5 (2007) stated that these functions
+A draft of X/Open Curses Issue\ 5
+(which never saw final release)
+stated that these functions
 \*(``read at most
 .I n
 bytes\*(''
@@ -378,7 +379,9 @@ .SH PORTABILITY
 .I xcurses
 limits the write to
 .I LINE_MAX
-bytes.
+bytes
+(see
+.IR sysconf (3)).
 .bP
 NetBSD 7
 .I curses
-- 
2.30.2

signature.asc
Description: PGP signature