[PATCH 075/100] man/ncurses.3x: Recast "Header Files" subsection and "AUTHORS" section.

[G. Branden Robinson]

Content:
* Fix error where "stdio.h" was written where "stdarg.h" was meant.
* Fix historical error claiming that, "initially", variadic argument
  lists were typed as pointers to void; they were pointers to char.  In
  fact, as far as I can tell, no Unix archived at TUHS ever migrated its
  varargs.h to the void pointer type; no point in it once stdarg.h was
  available, I reckon.
* Add a little historical detail.
* Make it clearer to the callow how the complexity of this story is
  bound up with the (long controversial) practice of having C compilers
  perform type checking.  I remember when variadic argument lists were
  considered deep voodoo (and they sometimes were, when you assumed
  they'd be passed on the stack, but they wound up in registers; after
  all the world was a VAX, all the world was an x86...).

Style:
* Italicize "curses".
* Refer to SVr* _curses_, not the OS a whole.
* Set names of curses functions in italics, _not_ bold, when referring
  to them generically (contrast with the ncurses implementation of them,
  which these man pages document).
* Use bold for verbal emphasis in a context where italics are already
  adjacent.
* Use typographer's quotes for quotation, not `"`.
* Drop angle brackets from header file names.  They are a detail of C
  preprocessor syntax that is not important to the discussion.  Set them
  in italics instead of roman, and protect them from automatic
  hyphenation.
* Set names of data types in italics, not bold.

Markup:
* Break input lines after commas.
* 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).
* Replace colon dangling at the end of a sentence with a period.  The
  subsequent use of (in one case) an indented block quote paragraph and
  (in another) bulleted paragraphs makes the structure clear.
* Favor present tense over future.
* Favor active voice over passive.
---
 man/ncurses.3x | 300 +++++++++++++++++++++++++++++++++++++------------
 1 file changed, 230 insertions(+), 70 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 59bca28aa..3fe2b32bf 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1985,108 +1985,268 @@ .SS "Padding Differences"
 but narrows the interface to the Unix kernel significantly and
 correspondingly increases the package's portability.
 .SS "Header Files"
-The header file \fI\%curses.h\fP itself includes the header files
-\fI\%stdio.h\fP and \fI\%unctrl.h\fP.
+The header file
+.I \%curses.h
+itself includes the header files
+.I \%stdio.h
+and
+.IR \%unctrl.h .
 .PP
 X/Open Curses has more to say,
-but does not finish the story:
 .RS 4
 .PP
-The inclusion of <curses.h> may make visible all symbols
-from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
+The inclusion of
+.I \%curses.h
+may make visible all symbols from the headers
+.IR \%stdio.h ,
+.IR \%term.h ,
+.IR \%termios.h ,
+and
+.IR \%wchar.h .
 .RE
 .PP
-Here is a more complete story:
+but does not finish the story.
+A more complete account follows.
 .bP
-Starting with BSD curses, all implementations have included <stdio.h>.
+Starting with 4BSD
+.I curses
+(1980)
+all implementations have provided a
+.I \%curses.h
+file.
 .IP
-BSD curses included <curses.h> and <unctrl.h> from an internal header
-file
-.I \%curses.ext
-(\*(``ext\*('' abbreviated \*(``externs\*('').
+BSD
+.I curses
+code included
+.I \%curses.h
+and
+.I \%unctrl.h
+from an internal header file
+.IR \%curses.ext ,
+where
+\*(``ext\*('' abbreviated \*(``externs\*(''.
 .IP
-BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
-but nothing in <curses.h> itself relied upon <stdio.h>.
+The implementations of
+.I \%printw
+and
+.I \%scanw
+used undocumented internal functions of the standard I/O library
+.RI ( _doprnt
+and
+.IR _doscan ),
+but nothing in
+.I \%curses.h
+itself relied upon
+.IR \%stdio.h .
 .bP
-SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>.
-That is, the function prototype uses \fBFILE\fP.
+SVr2
+.I curses
+added
+.IR \%newterm ,
+which relies upon
+.I \%stdio.h
+because its function prototype employs the
+.I FILE
+type.
 .IP
-SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>.
+SVr4
+.I curses
+added
+.I \%putwin
+and
+.IR \%getwin ,
+which also use
+.IR \%stdio.h .
 .IP
-X/Open Curses documents all three of these functions.
+X/Open Curses specifies all three of these functions.
 .IP
-SVr4 curses and X/Open Curses do not require the developer to
-include <stdio.h> before including <curses.h>.
-Both document curses showing <curses.h> as the only required header.
+SVr4
+.I curses
+and X/Open Curses do not require the developer to include
+.I \%stdio.h
+before
+.IR \%curses.h .
+Both document use of
+.I curses
+as requiring only
+.IR \%curses.h .
 .IP
-As a result, standard <curses.h> will always include <stdio.h>.
+As a result,
+standard
+.I \%curses.h
+always includes
+.IR \%stdio.h .
 .bP
-X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
+X/Open Curses and SVr4
+.I curses
+are inconsistent with respect to
+.IR \%unctrl.h .
 .IP
 As noted in \fBcurs_util\fP(3X),
-\fI\%ncurses\fP includes <unctrl.h> from <curses.h>
-(like SVr4).
+.I \%ncurses
+includes
+.I \%unctrl.h
+from
+.I \%curses.h
+(as SVr4 does).
 .bP
-X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
+X/Open Curses's comments about
+.I \%term.h
+and
+.I \%termios.h
+may refer to HP-UX and AIX.
 .IP
-HP-UX curses includes <term.h> from <curses.h>
-to declare \fBsetupterm\fP in curses.h,
-but \fI\%ncurses\fP (and Solaris curses) do not.
+HP-UX
+.I curses
+includes
+.I \%term.h
+from
+.I \%curses.h
+to declare
+.I \%setupterm
+in
+.IR \%curses.h ,
+but
+.I \%ncurses
+and Solaris
+.I curses
+do not.
 .IP
-AIX curses includes <term.h> and <termios.h>.
-Again, \fI\%ncurses\fP (and Solaris curses) do not.
+AIX
+.I curses
+includes
+.I \%term.h
+and
+.IR \% termios.h .
+Again,
+.I \%ncurses
+and Solaris
+.I curses
+do not.
 .bP
-X/Open says that <curses.h> \fImay\fP include <term.h>,
-but there is no requirement that it do that.
+X/Open Curses says that
+.I \%curses.h
+.B may
+include
+.IR \%term.h ,
+but does not require it to do so.
 .IP
-Some programs use functions declared in both <curses.h> and <term.h>,
-and must include both headers in the same module.
-Very old versions of AIX curses required including <curses.h>
-before including <term.h>.
+Some programs use functions declared in both
+.I \%curses.h
+and
+.IR \%term.h ,
+and must include both header files in the same module.
+Very old versions of AIX
+.I curses
+required inclusion of
+.I \%curses.h
+before
+.IR \%term.h .
 .IP
-Because \fI\%ncurses\fP header files include the headers needed to
-define datatypes used in the headers,
-\fI\%ncurses\fP header files can be included in any order.
-But for portability, you should include <curses.h> before <term.h>.
+The header files supplied by
+.I \%ncurses
+include the standard library headers required for its declarations,
+so
+.IR \%ncurses 's
+own header files can be included in any order.
+But for portability,
+you should include
+.I \%curses.h
+before
+.IR \%term.h .
 .bP
-X/Open Curses says \fI"may make visible"\fP
-because including a header file does not necessarily make all symbols
-in it visible (there are ifdef's to consider).
+X/Open Curses says \*(``may make visible\*('' because including a header
+file does not necessarily make visible all of the symbols in it
+(consider
+.B \%#ifdef
+and similar).
 .IP
-For instance, in \fI\%ncurses\fP <wchar.h> \fImay\fP be included if
-the proper symbol is defined, and if \fI\%ncurses\fP is configured for
-wide-character support.
-If the header is included, its symbols may be made visible.
-That depends on the value used for \fB_XOPEN_SOURCE\fP
+For instance,
+.IR \%ncurses 's
+.I \%curses.h
+.B may \" bold to contrast with preceding italic
+include
+.I \%wchar.h
+if the proper symbol is defined,
+and if
+.I \%ncurses
+is configured for wide-character support.
+If
+.I \%wchar.h
+is included,
+its symbols
+.B may \" bold for consistency in this paragraph
+be made visible depending on the value of the
+.B _XOPEN_SOURCE
 feature test macro.
 .bP
-X/Open Curses documents one required header,
-in a special case: <stdarg.h> before <curses.h> to prototype
-the \fBvw_printw\fP and \fBvw_scanw\fP functions
+X/Open Curses mandates an application's inclusion of one standard C
+library header in a special case:
+.I \%stdarg.h
+before
+.I \%curses.h
+to prototype the functions
+.I \%vw_printw
+and
+.I \%vw_scanw
 (as well as the obsolete
-the \fBvwprintw\fP and \fBvwscanw\fP functions).
-Each of those uses a \fBva_list\fP parameter.
+.I \%vwprintw
+and
+.IR \%vwscanw ).
+Each of these takes a variadic argument list,
+a
+.I \%va_list
+parameter,
+like that of \fI\%printf\fP(3).
 .IP
-The two obsolete functions were introduced in SVr3.
-The other functions were introduced in X/Open Curses.
-In between, SVr4 curses provided for the possibility that
-an application might include either <varargs.h> or <stdarg.h>.
-Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP
+SVr3
+.I curses
+introduced
+the two obsolete functions,
+and X/Open Curses the others.
+In between,
+SVr4
+.I curses
+provided for the possibility that an application might include either
+.I \%varargs.h
+or
+.IR \%stdarg.h .
+These represented contrasting approaches to handling variadic
+argument lists.
+The older interface,
+.IR \%varargs.h ,
+used a pointer to
+.I char \" V7, 32V, System III, 3BSD
+for variadic functions'
+.I \%va_list
 parameter.
-Later, a special type (defined in <stdio.h>) was introduced,
-to allow for compiler type-checking.
-That special type is always available,
-because <stdio.h> is always included by <curses.h>.
+Later,
+the list acquired its own standard data type,
+.IR \%va_list ,
+defined in
+.IR \%stdarg.h ,
+empowering the compiler to check the types of a function call's actual
+parameters against the formal ones declared in its prototype.
 .IP
-None of the X/Open Curses implementations require an application
-to include <stdarg.h> before <curses.h> because they either
-have allowed for a special type,
-or
-(like \fI\%ncurses\fP)
-include <stdarg.h> directly to provide a portable interface.
+No conforming implementations of X/Open Curses require an application
+to include
+.I \%stdarg.h
+before
+.I \%curses.h
+because they either have allowed for a special type,
+or,
+like
+.IR \%ncurses ,
+they include
+.I \%stdarg.h
+themselves to provide a portable interface.
 .SH AUTHORS
-Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
-Based on \fIpcurses\fP by Pavel Curtis.
+Zeyd M. Ben-Halim,
+Eric S. Raymond,
+Thomas E. Dickey.
+Based on
+.I \%pcurses
+by Pavel Curtis.
 .SH SEE ALSO
 \fB\%curs_variables\fP(3X),
 \fB\%terminfo\fP(5),
-- 
2.30.2

signature.asc
Description: PGP signature