[PATCH 12/52] man/curs_ins{,_w}ch.3x: Revise and parallelize.

[G. Branden Robinson]

Content:
* Drop erroneous use of "string" in summary description
  (curs_ins_wch.3x).
* Set #include line in bold (curs_ins_wch.3x).
* Move caveat about "insert character" capability from "DESCRIPTION" to
  "NOTES" section, and recast.
* Prefer "X/Open Curses, Issue 4" to "XSI Curses standard".
* Move caveat about SVr4's return values from "RETURN VALUE" to
  "PORTABILITY" section.
* Add cross reference to non-wide character counterparts
  (curs_insch.3x).
* Add cross reference to terminfo(5) since capabilities were raised.

Style:
* Group the usual curses 4-tuple of functions together in synopsis.
* Recast "DESCRIPTION" and "RETURN VALUE" sections.  Describe failure
  conditions more precisely.

Markup:
* Favor man(7) font style macros over *roff font selection escape
  sequences (except for man page cross references).
* Quote multi-word macro arguments.
---
 man/curs_ins_wch.3x | 73 ++++++++++++++++++++++++++++++++++-----------
 man/curs_insch.3x   | 70 ++++++++++++++++++++++++++++---------------
 2 files changed, 102 insertions(+), 41 deletions(-)

diff --git a/man/curs_ins_wch.3x b/man/curs_ins_wch.3x
index 8ef12e442..a92f2c779 100644
--- a/man/curs_ins_wch.3x
+++ b/man/curs_ins_wch.3x
@@ -44,32 +44,71 @@ .SH NAME
 \fB\%mvins_wch\fP,
 \fB\%mvwins_wch\fP,
 \fB\%wins_wch\fP \-
-insert a \fIcurses\fR complex character string in a window
+insert a \fIcurses\fR complex character in a window
 .SH SYNOPSIS
 .nf
-#include <curses.h>
+\fB#include <curses.h>\fP
 .PP
 \fBint ins_wch(const cchar_t *\fIwch\fP);
 \fBint wins_wch(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
-.PP
 \fBint mvins_wch(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP);
 \fBint mvwins_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t 
*\fIwch\fP);
 .fi
 .SH DESCRIPTION
-These routines, insert the complex character \fIwch\fP with rendition
-before the character under the cursor.
-All characters to the right of the cursor are moved one space to the right,
-with the possibility of the rightmost character on the line being lost.
-The insertion operation does not change the cursor position.
-.SH RETURN VALUE
-If successful, these functions return \fBOK\fP.
-If not, they return \fBERR\fP.
+These functions insert the
+.I curses
+complex character
+.I wch
+at the cursor in the specified window
+.I win
+(or
+.BR \%stdscr ).
+The character previously at the cursor and any to its right move one
+cell to the right;
+the rightmost character on the line is discarded.
+The cursor does not advance.
+.SH "RETURN VALUE"
+These functions return \fBOK\fP on success and \fBERR\fP on failure.
+.PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
 .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.
+Functions prefixed with \*(``mv\*('' first perform cursor movement using
+\fB\%wmove\fP and fail if the position
+.RI ( y ,
+.IR x )
+is outside the window.
+.SH NOTES
+A terminal's
+.B \%insert_character
+.RB ( ich1 )
+capability
+is not necessarily employed.
+.PP
+\fB\%ins_wch\fP,
+\fB\%mvins_wch\fP,
+and
+\fB\%mvwins_wch\fP
+may be implemented as macros.
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-.SH SEE ALSO
+X/Open Curses, Issue 4, describes these functions.
+.PP
+SVr4 describes successful return values only as
+\*(``an integer value other than \fBERR\fP\*(''.
+.SH HISTORY
+SVr4 (1989) implemented these functions under the names
+.BR inswch ,
+.BR winswch ,
+.BR mvinswch ,
+and
+.BR mvwinswch .
+.SH "SEE ALSO"
+\fB\%curs_insch\fP(3X) describes comparable functions in the
+non-wide-character
+.I curses
+configuration.
+.PP
 \fB\%curses\fP(3X),
-\fB\%curs_insch\fP(3X)
+\fB\%terminfo\fP(5)
diff --git a/man/curs_insch.3x b/man/curs_insch.3x
index 889ea4ac5..7254bf53f 100644
--- a/man/curs_insch.3x
+++ b/man/curs_insch.3x
@@ -47,39 +47,61 @@ .SH NAME
 insert a \fIcurses\fR character in a window
 .SH SYNOPSIS
 .nf
-\fB#include <curses.h>
+\fB#include <curses.h>\fP
 .PP
 \fBint insch(chtype \fIch\fP);
 \fBint winsch(WINDOW *\fIwin\fP, chtype \fIch\fP);
-.PP
 \fBint mvinsch(int \fIy\fP, int \fIx\fP, chtype \fIch\fP);
 \fBint mvwinsch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, chtype \fIch\fP);
 .fi
 .SH DESCRIPTION
-These routines insert the character \fIch\fP before the character under the
-cursor.
-All characters to the right of the cursor are moved one space to the
-right, with the possibility of the rightmost character on the line being lost.
-The insertion operation does not change the cursor position.
-.SH RETURN VALUE
-These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
-(SVr4 specifies only
-\*(``an integer value other than \fBERR\fP\*('')
-upon successful completion.
+These functions insert the
+.I curses
+character
+.I ch
+at the cursor in the specified window
+.I win
+(or
+.BR \%stdscr ).
+The character previously at the cursor and any to its right move one
+cell to the right;
+the rightmost character on the line is discarded.
+The cursor does not advance.
+.SH "RETURN VALUE"
+These functions return \fBOK\fP on success and \fBERR\fP on failure.
+.PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
 .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.
+Functions prefixed with \*(``mv\*('' first perform cursor movement using
+\fB\%wmove\fP and fail if the position
+.RI ( y ,
+.IR x )
+is outside the window.
 .SH NOTES
-These routines do not necessarily imply use of a hardware insert character
-feature.
+A terminal's
+.B \%insert_character
+.RB ( ich1 )
+capability
+is not necessarily employed.
 .PP
-Note that \fBinsch\fP, \fBmvinsch\fP, and \fBmvwinsch\fP may be macros.
+\fB\%insch\fP,
+\fB\%mvinsch\fP,
+and
+\fB\%mvwinsch\fP
+may be implemented as macros.
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-.SH SEE ALSO
-\fB\%curses\fP(3X)
+X/Open Curses, Issue 4, describes these functions.
+.PP
+SVr4 describes successful return values only as
+\*(``an integer value other than \fBERR\fP\*(''.
+.SH "SEE ALSO"
+\fB\%curs_ins_wch\fP(3X) describes comparable functions in the
+wide-character
+.I curses
+configuration.
 .PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fB\%curs_ins_wch\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
-- 
2.30.2

signature.asc
Description: PGP signature