[PATCH 20/43] man/curs_kernel.3x: Revise "PORTABILITY" section.

[G. Branden Robinson]

Content:
* Document caveats regarding `curs_set()` and `ripoffline()`.

Style:
* Collect discussion of `getsyx()` and `setsyx()` into one paragraph.
* Drop comma separating "X/Open Curses" from a subsequent "Issue".  The
  ncurses man pages are reliably inconsistent about this.
* Use unbreakable space in "Issue 4".
* Lightly recast.
* Drop quotation marks from block quotation.
* Set function names in italics, not bold, when referring to them
  generically (as in the "PORTABILITY" and "HISTORY" sections) as
  opposed to the ncurses topic/implementation.
* 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).
---
 man/curs_kernel.3x | 51 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x
index 457db4da2..b0c012ebb 100644
--- a/man/curs_kernel.3x
+++ b/man/curs_kernel.3x
@@ -304,24 +304,45 @@ .SH PORTABILITY
 .B \%NCURSES_VERSION
 preprocessor macro.
 .PP
-The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP
-are not described in X/Open Curses, Issue 4.
+The
+.I "virtual screen"
+functions
+.I \%setsyx
+and
+.I \%getsyx
+are not described in X/Open Curses Issue\ 4.
+SVr4 documents each of them
+as returning an
+.IR int "."
+This is misleading,
+as they are macros with no documented semantics for returning values.
+.PP
 All other functions are as described in X/Open Curses.
+It specifies no error conditions for them,
+except as described for
+.I \%curs_set
+in section \*(``RETURN VALUE\*('' above.
 .PP
-The SVr4 documentation describes \fBsetsyx\fP and \fBgetsyx\fP
-as having return type int.
-This is misleading, as they are macros with no documented semantics
-for the return value.
+X/Open Curses specifies
+.I \%ripoffline
+as returning
+.B OK
+with no possibility of failure
+(\*(``[c]alls to
+.I \%ripoffline
+above this limit
+[five lines]
+have no effect but report success\*('').
 .PP
 X/Open Curses notes:
 .RS
 .PP
-\*(``After use of
+After use of
 .IR \%mvcur "(),"
 the model Curses maintains of the state of the terminal might not
 match the actual state of the terminal.
 An application should touch and refresh the window before
-resuming conventional use of Curses.\*(''
+resuming conventional use of Curses.
 .RE
 .PP
 Both
@@ -332,15 +353,19 @@ .SH PORTABILITY
 .B \%mvcur
 using the
 .I SCREEN
-data allocated in either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X).
+object allocated in either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X).
 X/Open Curses states that the old location must be given for
-.B \%mvcur
+.I \%mvcur
 to accommodate terminals that lack absolute cursor positioning.
 .\" X/Open Curses Issue 7, p. 161
 .PP
-If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP.
-That, and the limitation to 30 seconds,
-are different from other implementations.
+If interrupted by a signal,
+.I \%ncurses
+restarts
+.IR \%napms "."
+That,
+and the limitation to 30 seconds,
+differ from other implementations.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_initscr\fP(3X),
-- 
2.30.2

signature.asc
Description: PGP signature