[PATCH 51/51] man/curs_deleteln.3x: Revise.

[G. Branden Robinson]

Content:
* Discuss elemental functions first, and delegate explanation of the
  other variants to ncurses(3X) as usual.
* Discuss `winsertln()` before `winsdelln()`, since the latter is more
  complex.
* Discuss function behavior more explicitly in terms of formal arguments
  and return values.
* Document that the "blank character" populates emptied lines, and cross
  reference wbkgset(3X) and wbkgrndset(3X) accordingly.
* Recharacterize `winsdelln()` as behaving as if by repeated calls to
  `winsertln()` or `wdeleteln()`.
* Move observation of X/Open Curses's lack of error condition
  specification from "RETURN VALUE" section to "PORTABILITY" section.
* Cross reference idlok(3X) and defer to its discussion of why hardware
  line insertion and deletion capabilities are unused by default.
* Add caveat about SVr4's loosely defined return value.
* Add "HISTORY" section.

Style:
* Parallelize wording of "DESCRIPTION", "RETURN VALUE", "NOTES", and
  "PORTABILITY" sections with other recent changes to ncurses man pages.
* Favor saying "ncurses" over "this implementation".
* Recast.

Markup:
* Protect ncurses function names from hyphenation.
* 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).
---
 man/curs_deleteln.3x | 101 ++++++++++++++++++++++++++++++-------------
 1 file changed, 71 insertions(+), 30 deletions(-)

diff --git a/man/curs_deleteln.3x b/man/curs_deleteln.3x
index a65a1633b..0242dbb7b 100644
--- a/man/curs_deleteln.3x
+++ b/man/curs_deleteln.3x
@@ -62,43 +62,84 @@ .SH SYNOPSIS
 \fBint winsdelln(WINDOW * \fIwin\fP, int \fIn\fP);
 .fi
 .SH DESCRIPTION
-The \fBdeleteln\fP and \fBwdeleteln\fP routines delete the line under the
-cursor in the window; all lines below the current line are moved up one line.
-The bottom line of the window is cleared.
+.B \%wdeleteln
+deletes the line at the cursor in
+.IR win ;
+all lines below it move up one line.
+.I curses
+then fills the bottom line of
+.I win
+with the blank character
+configured by \fB\%wbkgdset\fP(3X)
+(wide-character API users: \fB\%wbkgrndset\fP(3X)).
 The cursor position does not change.
 .PP
-The \fBinsdelln\fP and \fBwinsdelln\fP routines, for positive \fIn\fP, insert
-\fIn\fP lines into the specified window above the current line.
-The \fIn\fP
-bottom lines are lost.
-For negative \fIn\fP, delete \fIn\fP lines (starting
-with the one under the cursor), and move the remaining lines up.
-The bottom
-\fIn\fP lines are cleared.
-The current cursor position remains the same.
+.B \%winsertln
+inserts a line of blank characters above the line at the cursor in
+.IR win ;
+the content of the window's bottom line is lost.
+The cursor position does not change.
+.PP
+.B \%winsdelln
+inserts or deletes
+.IR n\  lines
+in
+.I win
+as
+.I n
+is positive or negative,
+respectively,
+as if by repeatedly calling
+.B \%winsertln
+or
+.BR \%wdeleteln "."
 .PP
-The \fBinsertln\fP and \fBwinsertln\fP routines insert a blank line above the
-current line and the bottom line is lost.
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .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 return
+.B OK
+on success and
+.B ERR
+on failure.
 .PP
-X/Open defines no error conditions.
-In this implementation,
-if the window parameter is null, an error is returned.
+In
+.IR \%ncurses ","
+they fail if
+.I win
+is
+.BR NULL "."
 .SH NOTES
-Note that all but \fBwinsdelln\fP may be macros.
+All of these functions except
+.B \%winsdelln
+may be implemented as macros.
 .PP
-These routines do not require a hardware line delete or insert feature in the
-terminal.
-In fact, they will not use hardware line delete/insert unless
-\fBidlok(..., TRUE)\fP has been set on the current window.
+These functions do not require the terminal
+to possess hardware line deletion or insertion capabilities.
+Even if available,
+by default
+.I curses
+does not use them;
+see \fB\%idlok\fP(3X).
 .SH PORTABILITY
-These functions are described in X/Open Curses, Issue 4.
-The
-standard specifies that they return \fBERR\fP on failure, but specifies no
-error conditions.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
+.SH HISTORY
+4BSD (1980)
+.I curses
+introduced
+.I \%wdeleteln
+and
+.IR \%winsertln "."
+.PP
+SVr3.1 (1987)
+added
+.IR \%winsdelln "."
 .SH SEE ALSO
 \fB\%curses\fP(3X)
-- 
2.30.2

signature.asc
Description: PGP signature