[PATCH 14/61] man/ncurses.3x: Explain use of man page sections.

[G. Branden Robinson]

Present them in (what I'm trying to mash into) a consistent order and
explain the material each one covers, based on slowly drawn inferences
and much exasperation with inconsistent practice in current usage.

The idea is sort them roughly in the order an ncurses user would want
likely want to know about them.

* First, implementation details they need to be aware of even if they
  care nothing for portability or *curses history.
* Next, extensions, so that they at least know they're getting off the
  beaten (standardized) track even if they're indifferent to whether
  what they're writing will work on, say, NetBSD curses or SVr4.
* Then, the portability details of various implementations, particularly
  where they clash with the standard(s).
* Finally, why things look the way they do today: the millstones of
  history.

This is partly my prescription, but also what I perceive--through some
pretty dark glass--the intent of the various page authors to be.
---
 man/ncurses.3x | 39 +++++++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 10 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 8cf20aee..65d826e2 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -68,16 +68,35 @@ .SH DESCRIPTION
 and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
 XSI stands for X/Open System Interfaces Extension.
 The \fBncurses\fP library is freely redistributable in source form.
-Differences from the SVr4
-curses are summarized under the
-\fIEXTENSIONS\fP and \fIPORTABILITY\fP sections below and
-described in detail in the respective
-\fIEXTENSIONS\fP, \fIPORTABILITY\fP and \fIBUGS\fP sections
-of individual man pages.
-.PP
-The \fBncurses\fP library also provides many useful extensions,
-i.e., features which cannot be implemented by a simple add-on library
-but which require access to the internals of the library.
+.PP
+\fI\%ncurses\fP man pages employ several sections to clarify matters of
+usage and interoperability with other \fIcurses\fP implementations.
+.bP
+\*(``NOTES\*('' describes matters and caveats of which any user of the
+\fI\%ncurses\fP API should be aware,
+such as limitations on the size of an underlying integral type or the
+availability of a preprocessor macro for a function
+(which prevents its address from being taken).
+This section also describes implementation details that will be
+significant to the programmer but which are not standardized.
+.bP
+\*(``EXTENSIONS\*('' presents \fI\%ncurses\fP innovations beyond the
+X/Open Curses standard and/or the SVr4 \fIcurses\fP implementation.
+They are termed \fIextensions\fP to indicate that they cannot be
+implemented solely by using the library API, but require access to the
+library's internal state.
+.bP
+\*(``PORTABILITY\*('' discusses matters
+(beyond the exercise of extensions)
+that should be considered when writing to a \fIcurses\fP standard,
+or to multiple implementations.
+.bP
+\*(``HISTORY\*('' examines points of detail in \fI\%ncurses\fP and other
+\fIcurses\fP implementations over the decades of their development,
+particularly where precedent or inertia have frustrated better design
+(and,
+in a few cases,
+where such inertia has been overcome).
 .PP
 A program using these routines must be linked with the \fB\-lncurses\fP option,
 or (if it has been generated) with the debugging library \fB\-lncurses_g\fP.
-- 
2.30.2

signature.asc
Description: PGP signature