[PATCH 08/20] man/ncurses.3x: Consolidate discussion of extensions.

[G. Branden Robinson]

+ Retire "Extensions Versus Portability" subsection, relocating its
  content into "EXTENSIONS" section, combining it with an incompletely
  overlapping list of extensions.  The top of the page explains the
  distinction.
+ Document `has_key()` extension; briefly explain what it does.
+ Disclose what the soft-label key extension functions do, and motivate
  them in the context of standard functions.
+ Segregate discussion of build-time configuration-dependent extensions,
  to aid readers who might be wondering why the version of ncurses
  they're using is missing them; cross-reference "ALTERNATE
  CONFIGURATIONS" subsection for the same reason.
+ Drop redundant statements of "not part of XPG4".
+ Drop notations of non-presence in SVr4; that's covered in the man
  pages documenting the individual functions.
+ Resequence list of extensions to present what (I would suppose) are
  those of greater user interest earlier, and obscure or discouraged
  extensions (like "-DUSE_GETCAP") later.
+ Recast language to employ a variety of verbs, for the
  non-stultification of the reader.
+ Drop unnecessary language when cross-referencing a man page; phrases
  like "for more details" are implied by the act of reference.
+ Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references.
+ Use unbreakable spaces in "ISO 6429" (instead of a hyphen) and "SGR
  [34]9".

* man/man_db.renames.in: Rewrite newly added man page cross references.
---
 man/man_db.renames.in |   6 ++
 man/ncurses.3x        | 158 +++++++++++++++++++++++-------------------
 2 files changed, 91 insertions(+), 73 deletions(-)

diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 9570b2980..fe3fe6715 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -190,17 +190,21 @@ delscreen.3x                      delscreen.3ncurses
 derwin.3x                      derwin.3ncurses
 doupdate.3x                    doupdate.3ncurses
 endwin.3x                      endwin.3ncurses
+extended_slk_color.3x          extended_slk_color.3ncurses
 filter.3x                      filter.3ncurses
 flushinp.3x                    flushinp.3ncurses
 get_wch.3x                     get_wch.3ncurses
+getattr.3x                     getattr.3ncurses
 getcchar.3x                    getcchar.3ncurses
 getch.3x                       getch.3ncurses
+has_key.3x                     has_key.3ncurses
 idcok.3x                       idcok.3ncurses
 idlok.3x                       idlok.3ncurses
 immedok.3x                     immedok.3ncurses
 in_wch.3x                      in_wch.3ncurses
 inch.3x                                inch.3ncurses
 initscr.3x                     initscr.3ncurses
+is_scrollok.3x                 is_scrollok.3ncurses
 keyname.3x                     keyname.3ncurses
 keypad.3x                      keypad.3ncurses
 leaveok.3x                     leaveok.3ncurses
@@ -222,6 +226,8 @@ set_curterm.3x                      set_curterm.3ncurses
 set_term.3x                    set_term.3nses
 setcchar.3x                    setcchar.3ncurses
 setupterm.3x                   setupterm.3ncurses
+slk_attr.3x                    slk_attr.3ncurses
+slk_color.3x                   slk_color.3ncurses
 slk_init.3x                    slk_init.3ncurses
 slk_touch.3x                   slk_touch.3ncurses
 start_color.3x                 start_color.3ncurses
diff --git a/man/ncurses.3x b/man/ncurses.3x
index 39cae840e..9767489bf 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1567,50 +1567,97 @@ .SH NOTES
 inclusion of \fI\%curses.h\fP.
 .SH EXTENSIONS
 .I \%ncurses
-can be compiled with an option
-.RB ( \%\-DUSE_GETCAP )
-that falls back to reading
+enables an application to capture mouse events on certain terminals,
+including
+.I \%xterm;
+see \fB\%curs_mouse\fP(3X).
+.PP
+.I \%ncurses
+provides a means of responding to window resizing events,
+as when running in a GUI terminal emulator application such as
+.I \%xterm;
+see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
+.PP
+.I \%ncurses
+empowers an application to query the terminal for the presence of a wide
+variety of special keys;
+see \fB\%has_key\fP(3X).
+.PP
+.I \%ncurses
+extends the fixed set of function key capabilities specified by X/Open
+Curses by allowing the application programmer to define additional key
+sequences at runtime;
+see
+\fB\%define_key\fP(3X),
+\fB\%key_defined\fP(3X),
+and
+\fB\%keyok\fP(3X).
+.PP
+.I \%ncurses
+can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
+SGR\ 39 and SGR\ 49 sequences,
+which allow an application to reset the terminal to its original
+foreground and background colors.
+From a user's perspective,
+the application is able to draw colored text on a background whose color
+is set independently,
+providing better control over color contrasts.
+See \fB\%default_colors\fP(3X).
+.PP
+An
+.I \%ncurses
+application can choose to hide the internal details of
+.I \%WINDOW
+structures,
+instead using accessor functions such as
+\fB\%is_scrollok\fP(3X).
+.PP
+.I \%ncurses
+enables an application to direct application output to a printer
+attached to the terminal device;
+see \fB\%curs_print\fP(3X).
+.PP
+.I \%ncurses
+offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%getattr\fP(3X) for
+soft-label key lines,
+and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
+that can gather color information from them when many colors are
+supported.
+.PP
+Some extensions are only available if
+.I \%ncurses
+is compiled to support them;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' above.
+.bP
+Rudimentary support for multi-threaded applications may be available;
+see \fBcurs_threads\fP(3X).
+.bP
+Functions that ease the management of multiple screens can be exposed;
+see \fBcurs_sp_funcs\fP(3X).
+.bP
+The compiler option
+.B \%\-DUSE_GETCAP
+causes the library to fall back to reading
 .I \%/etc/termcap
 if the terminal setup code cannot find a
 .I \%term\%info
 entry corresponding to
 .I TERM.
 Use of this feature is not recommended,
-as it essentially includes an entire termcap compiler in the
-\fI\%ncurses\fP startup code,
-at significant cost in core and startup cycles.
-.PP
-The \fI\%ncurses\fP library includes facilities for capturing mouse
-events on certain terminals
-(including xterm).
-See the \fBcurs_mouse\fP(3X)
-manual page for details.
-.PP
-The \fI\%ncurses\fP library includes facilities for responding to window
-resizing events, e.g., when running in an xterm.
-See the \fBresizeterm\fP(3X)
-and \fBwresize\fP(3X) manual pages for details.
-In addition, the library may be configured with a \fBSIGWINCH\fP handler.
-.PP
-The \fI\%ncurses\fP library extends the fixed set of function key
-capabilities of terminals by allowing the application designer to define
-additional key sequences at runtime.
-See the \fBdefine_key\fP(3X)
-\fBkey_defined\fP(3X),
-and \fBkeyok\fP(3X) manual pages for details.
-.PP
-The \fI\%ncurses\fP library can exploit the capabilities of terminals
-which implement the ISO\-6429 SGR 39 and SGR 49 controls,
-which allow an application to reset the terminal to its original
-foreground and background colors.
-From the users' perspective, the application is able to draw colored
-text on a background whose color is set independently, providing better
-control over color contrasts.
-See the \fBdefault_colors\fP(3X) manual page for details.
-.PP
-The \fI\%ncurses\fP library includes a function for directing
-application output to a printer attached to the terminal device.
-See the \fBcurs_print\fP(3X) manual page for details.
+as it essentially includes an entire
+.I termcap
+compiler in the
+.I \%ncurses
+startup code,
+at a cost in memory usage and application launch latency.
+.PP
+.I \%PDCurses
+and NetBSD
+.I curses
+incorporate some
+.I \%ncurses
+extensions.
+Individual man pages indicate where this is the case.
 .SH PORTABILITY
 X/Open Curses defines two levels of conformance,
 \*(``base\*('' and \*(``enhanced\*(''.
@@ -1637,41 +1684,6 @@ .SS "Error Checking"
 to tell an application which of several possible errors were detected.
 Relying on this (or some other) extension will adversely affect the
 portability of curses applications.
-.SS "Extensions Versus Portability"
-Most of the extensions provided by \fI\%ncurses\fP have not been
-standardized.
-Some have been incorporated into other implementations, such as
-PDCurses or NetBSD curses.
-Here are a few to consider:
-.bP
-The routine \fBhas_key\fP is not part of XPG4, nor is it present in SVr4.
-See the \fBcurs_getch\fP(3X) manual page for details.
-.bP
-The routine \fBslk_attr\fP is not part of XPG4, nor is it present in SVr4.
-See the \fBcurs_slk\fP(3X) manual page for details.
-.bP
-The routines \fBgetmouse\fP, \fBmousemask\fP, \fBungetmouse\fP,
-\fBmouseinterval\fP, and \fBwenclose\fP relating to mouse interfacing are not
-part of XPG4, nor are they present in SVr4.
-See the \fBcurs_mouse\fP(3X) manual page for details.
-.bP
-The routine \fBmcprint\fP was not present in any previous curses 
implementation.
-See the \fBcurs_print\fP(3X) manual page for details.
-.bP
-The routine \fBwresize\fP is not part of XPG4, nor is it present in SVr4.
-See the \fBwresize\fP(3X) manual page for details.
-.bP
-The \fI\%WINDOW\fP structure's internal details can be hidden from application
-programs.
-See \fBcurs_opaque\fP(3X) for the discussion of \fBis_scrollok\fP, etc.
-.bP
-This implementation can be configured to provide rudimentary support
-for multi-threaded applications.
-See \fBcurs_threads\fP(3X) for details.
-.bP
-This implementation can also be configured to provide a set of functions which
-improve the ability to manage multiple screens.
-See \fBcurs_sp_funcs\fP(3X) for details.
 .SS "Padding Differences"
 In historic curses versions, delays embedded in the capabilities \fBcr\fP,
 \fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay
-- 
2.30.2

signature.asc
Description: PGP signature