[PATCH 19/20] man/ncurses.3x: Fix content, style, and markup nits.

[G. Branden Robinson]

Content:
* Clarify what the "NOTES" section is (will be) for.  Thomas's change to
  this page in snapshot 20231223 suggests that we need not burden dozens
  of pages with annotations about functions being available as macros,
  since X/Open Curses permits a great many such functions to be treated
  thus.  Instead, it would be better to document the fact in this page
  (as is now done) and document only exceptional cases in
  function-specific pages.
* Say more about the widths of curses integral data types.
* Say less about the cursor advancing for spacing characters "on input";
  whether it does so on input or output is a matter of perspective,
  especially in full-duplex operation.

Style:
* Set "curses" in italics, not bold or roman.
* Lightly recast.

Markup:
* Protect man page names cross references from hyphenation.
---
 man/ncurses.3x | 57 ++++++++++++++++++++++++++++----------------------
 1 file changed, 32 insertions(+), 25 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index f3af89e9d..6d9d72103 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -76,7 +76,7 @@ .SH DESCRIPTION
 \*(``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
+availability of a preprocessor macro exclusive of a function definition
 (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.
@@ -358,7 +358,9 @@ .SS "Wide and Non-wide Character Configurations"
 handling only eight-bit characters.
 It stores a character combined with attributes in a
 .I \%chtype
-datum.
+datum,
+which is often an alias of
+.I int.
 .IP
 Attributes alone
 (with no corresponding character)
@@ -391,8 +393,8 @@ .SS "Wide and Non-wide Character Configurations"
 corresponds to the non-wide configuration's
 .I \%chtype.
 It always a structure type,
-because it stores more data than can fit into an integer.
-A character code may be larger than can fit in a C
+because it stores more data than fits into an integral type.
+A character code may not be representable as a
 .I \%char,
 and moreover more than one character may occupy a cell
 (as with accent marks and other diacritics).
@@ -405,9 +407,8 @@ .SS "Wide and Non-wide Character Configurations"
 structure,
 not combined as in
 .I \%chtype.
-.IP
-Each cell
-(row and column)
+.PP
+Each cell of a
 .I \%WINDOW
 is stored as a
 .I \%cchar_t.
@@ -424,18 +425,19 @@ .SS "Wide and Non-wide Character Configurations"
 stores a wide character.
 Like
 .I \%chtype,
-this may be an integer.
+it may be an alias of
+.I int.
 Depending on the character encoding,
 a wide character may be
 .I spacing,
 meaning that it occupies a character cell by itself and typically
-accompanies cursor advancement on input,
+accompanies cursor advancement,
 or
 .I non-spacing,
 meaning that it occupies the same cell as a spacing character,
 is often regarded as a \*(``modifier\*('' of the base glyph with which
 it combines,
-and typically does not advance the cursor on input.
+and typically does not advance the cursor.
 .TP 9
 .I \%wint_t
 can store a
@@ -1509,19 +1511,20 @@ .SH "ALTERNATE CONFIGURATIONS"
 Those functions are described in these pages:
 .RS
 .bP
-\fBcurs_extend\fP(3X) \- miscellaneous curses extensions
+\fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
 .bP
-\fBcurs_inopts\fP(3X) \- \fBcurses\fP input options
+\fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
 .bP
-\fBcurs_kernel\fP(3X) \- low-level \fBcurses\fP routines
+\fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
 .bP
-\fBcurs_termattrs\fP(3X) \- \fBcurses\fP environment query routines
+\fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
 .bP
-\fBcurs_termcap\fP(3X) \- \fBcurses\fP emulation of termcap
+\fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
 .bP
-\fBcurs_terminfo\fP(3X) \- \fBcurses\fP interfaces to terminfo database
+\fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
+database
 .bP
-\fBcurs_util\fP(3X) \- miscellaneous \fBcurses\fP utility routines
+\fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
 .RE
 .TP 5
 \-\-with\-trace
@@ -1537,24 +1540,28 @@ .SH FILES
 .I \*d
 compiled terminal capability database
 .SH NOTES
-\fI\%ncurses\fP implements many functions as macros as well.
-It does so
+X/Open Curses permits most functions it specifies to be made available
+as macros as well.
+.\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
+.\" See X/Open Curses Issue 7, pp. 311-318.
+\fI\%ncurses\fP does so
 .bP
 for functions that return values via their parameters,
 .bP
 to support obsolete features,
 .bP
-to reuse functions,
+to reuse functions
 (for example,
-those that move the cursor before another operation)
+those that move the cursor before another operation),
 and
 .bP
 a few special cases.
 .PP
-If standard output from a \fI\%ncurses\fP program is re-directed to
-something which is not a tty,
-screen updates will be directed to standard error.
-This was an undocumented feature of AT&T System V Release 3 curses.
+If the standard output file descriptor of an
+.I \%ncurses
+program is redirected to something that is not a terminal device,
+the library writes screen updates to the standard error file descriptor.
+This was an undocumented feature of SVr3.
 .PP
 See subsection \*(``Header files\*('' below regarding symbols exposed by
 inclusion of \fI\%curses.h\fP.
-- 
2.30.2

signature.asc
Description: PGP signature