[PATCH 16/30] man/curs_instr.3x: Revise.

[G. Branden Robinson]

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 `winstr()` first in "DESCRIPTION" section.
  Then describe how `winnstr()` 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.
* Relocate material about function behavior from "PORTABILITY" section
  to "DESCRIPTION" section.
* Fix erroneous argument reference: "chstr" -> "str".
* Refer to formal arguments by name, not type.
* Refer to null pointers as argument values by language literal, not
  concept.
* 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.
* Discuss disagreement between SVr4 behavior and X/Open Curses
  specification regarding the return value of `winstr()` and its
  variants.
* Add "HISTORY" section.

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_instr.3x | 172 +++++++++++++++++++++++++++++++++++-----------
 1 file changed, 132 insertions(+), 40 deletions(-)

diff --git a/man/curs_instr.3x b/man/curs_instr.3x
index 03ba13baf..62852901b 100644
--- a/man/curs_instr.3x
+++ b/man/curs_instr.3x
@@ -58,37 +58,69 @@ .SH SYNOPSIS
 .nf
 \fB#include <curses.h>
 .PP
-\fBint instr(char *\fIstr\fP);
-\fBint innstr(char *\fIstr\fP, int \fIn\fP);
-\fBint winstr(WINDOW *\fIwin\fP, char *\fIstr\fP);
-\fBint winnstr(WINDOW *\fIwin\fP, char *\fIstr\fP, int \fIn\fP);
+\fBint instr(char *\ \fIstr\fP);
+\fBint winstr(WINDOW *\ \fIwin\fP, char *\ \fIstr\fP);
+\fBint mvinstr(int \fIy\fP, int \fIx\fP, char *\ \fIstr\fP);
+\fBint mvwinstr(WINDOW *\ \fIwin\fP, int \fIy\fP, int \fIx\fP, char *\ 
\fIstr\fP);
 .PP
-\fBint mvinstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
-\fBint mvinnstr(int \fIy\fP, int \fIx\fP, char *\fIstr\fP, int \fIn\fP);
-\fBint mvwinstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP);
-\fBint mvwinnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, char *\fIstr\fP, 
int \fIn\fP);
+\fBint innstr(char *\ \fIstr\fP, int \fIn\fP);
+\fBint winnstr(WINDOW *\ \fIwin\fP, char *\ \fIstr\fP, int \fIn\fP);
+\fBint mvinnstr(int \fIy\fP, int \fIx\fP, char *\ \fIstr\fP, int \fIn\fP);
+\fBint mvwinnstr(WINDOW *\ \fIwin\fP, int \fIy\fP, int \fIx\fP, char *\ 
\fIstr\fP, int \fIn\fP);
 .fi
 .SH DESCRIPTION
-These routines return a string of characters in \fIstr\fP,
-starting at the current cursor position in the named window.
-Attributes are stripped from the characters.
-.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 \fIstr\fP.
+.B \%winstr
+extracts a 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 str ","
+terminating it with a null character
+and
+omitting any attributes and color pair identifier
+that
+.I curses
+associates with each character.
+.B \%winnstr
+does the same,
+but copies at most
+.I n
+characters from
+.IR win "."
+An
+.I n
+of
+.B \-1
+implies no limit;
+.B \%winnstr
+then works like
+.BR \%winstr "."
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .SH RETURN VALUE
-All of the functions return \fBERR\fP upon failure,
-or the number of characters actually read into the string.
+These functions return the count of characters copied from
+.I win
+to
+.IR str ","
+or
+.B ERR
+upon failure.
 .PP
-X/Open Curses defines no error conditions.
-This implementation returns
+In
+.IR \%ncurses ","
+they return
 .B ERR
+if
 .bP
-if the \fIwin\fP parameter is null or
+.I win
+is
+.B NULL
+or
 .bP
-if the \fIchstr\fP parameter is null.
+.I str
+is
+.BR NULL "."
 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
@@ -96,30 +128,90 @@ .SH RETURN VALUE
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-All routines except \fBwinnstr\fP may be macros.
+All of these functions except
+.B \%winnstr
+may be implemented as macros.
 .PP
 Reading a line that overflows the array pointed to by
-\fIstr\fP
+.I str
 with
-\fBinstr\fP,
-\fBmvinstr\fP,
-\fBmvwinstr\fP
+.BR \%instr ","
+.BR \%winstr ","
+.BR \%mvinstr ","
 or
-\fBwinstr\fP
+.B \%mvwinstr
 causes undefined results.
-Therefore, the use of
-\fBinnstr\fP,
-\fBmvinnstr\fP,
-\fBmvwinnstr\fP, or
-\fBwinnstr\fP
-is recommended.
+Use of
+.BR \%innstr ","
+.BR \%winnstr ","
+.BR \%mvinnstr ","
+and
+.B \%mvwinnstr
+is recommended instead.
+.SH EXTENSIONS
+.BR \%innstr ","
+.BR \%winnstr ","
+.BR \%mvinnstr ","
+and
+.BR \%mvwinnstr "'s"
+treatment of
+.B \-1
+as a valid value of
+.I n
+is an
+.I \%ncurses
+extension.
 .SH PORTABILITY
-SVr4 does not
-document whether a length limit includes or excludes the trailing NUL.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
 .PP
-The \fI\%ncurses\fP library extends the X/Open Curses description by allowing a
-negative value for \fIn\fP.
-In this case, the functions return the string ending at the right margin.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+X/Open Curses Issues 4 and 7 both state that
+.BR \%instr ","
+.BR \%winstr ","
+.BR \%mvinstr ","
+and
+.B \%mvwinstr
+return
+.B OK
+rather than a character count.
+This is likely an erratum.
+.bP
+SVr3.1 and SVr4 implemented
+.B \%winstr
+as a wrapper around
+.BR \%winnstr ","
+returning the latter's return value.
+X/Open Curses's specification thus may have been an editorial solecism
+copied from System\ V's documentation
+(see below)
+by X/Open,
+rather than an intentional change.
+.bP
+.I \%ncurses
+retains compatibility with System\ V
+.I curses
+behavior.
+.PP
+SVr4 documents no return values apart from
+.B OK
+and
+.B ERR
+for any of these functions.
+SVr4 does not
+document whether
+.I n
+counts the null terminator that these functions write to
+.IR str "."
+.SH HISTORY
+SVr3.1 (1987)
+introduced these functions.
 .SH SEE ALSO
 \fB\%curs_inwstr\fP(3X) describes comparable functions of the
 .I \%ncurses
-- 
2.30.2

signature.asc
Description: PGP signature