[PATCH 030/100] man/ncurses.3x: Revise "Overview" subsection.

[G. Branden Robinson]

Content:
* Migrate terminology: "line-drawing" -> "forms-drawing".
* Drop man page cross reference.  At this point in the page we're not
  sweating the wide-character API yet.
* Motivate `wrefresh()` a bit more.
* Give a sentence to the panel, form, and menu libraries.

Style:
* Protect man page topic names from automatic hyphenation.
* Vary wording.
---
 man/ncurses.3x | 58 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 21 deletions(-)

diff --git a/man/ncurses.3x b/man/ncurses.3x
index c3d7229b4..a84d92c9e 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -231,20 +231,23 @@ .SS Overview
 .RI ( y ,
 .IR x ),
 with the upper left corner as (0, 0).
-A window called \fB\%stdscr\fP,
+A window called
+.BR \%stdscr ,
 the same size as the terminal screen,
 is always available.
 Create others with \fB\%newwin\fP(3X).
 .PP
 A
 .I curses
-library does not manage overlapping windows.
-(See \fBpanel\fP(3X) if you desire this.)
-You can either use \fB\%stdscr\fP to manage one screen-filling window,
+library does not manage overlapping windows
+(but see below).
+You can either use
+.B \%stdscr
+to manage one screen-filling window,
 or tile the screen into non-overlapping windows and not use
-\fB\%stdscr\fP at all.
-Mixing the two approaches will result in unpredictable,
-and undesired,
+.B \%stdscr
+at all.
+Mixing the two approaches will result in unpredictable and undesired
 effects.
 .PP
 Functions permit manipulation of a window and the
@@ -252,7 +255,7 @@ .SS Overview
 identifying the cell within it at which the next output operation will
 occur.
 Among those,
-the most basic are \fBmove\fP(3X) and \fB\%addch\fP(3X):
+the most basic are \fB\%move\fP(3X) and \fB\%addch\fP(3X):
 these place the cursor and write a character to
 .BR \%stdscr ,
 respectively.
@@ -287,10 +290,9 @@ .SS Overview
 .I x
 coordinate pair.
 .PP
-Updating the terminal screen with every
-.I curses
-call can cause unpleasant flicker or inefficient use of the
-communications channel to the device.
+Frequent changes to the terminal screen can cause unpleasant flicker or
+inefficient use of the communication channel to the device,
+so the library does not generally update it automatically.
 Therefore,
 after using
 .I curses
@@ -298,7 +300,7 @@ .SS Overview
 present together,
 call \fB\%refresh\fP(3X) to tell the library to make the user's screen
 look like \fBstdscr\fP.
-.I \%ncurses
+The library
 .\" X/Open Curses Issue 7 assumes some optimization will be done, but
 .\" does not mandate it in any way.
 .I optimizes
@@ -312,7 +314,9 @@ .SS Overview
 .I curses
 implementation.
 .PP
-Special windows called \fIpads\fP may also be manipulated.
+Special windows called
+.I pads
+may also be manipulated.
 These are windows that are not constrained to the size of the terminal
 screen and whose contents need not be completely displayed.
 See \fB\%curs_pad\fP(3X).
@@ -325,12 +329,10 @@ .SS Overview
 See \fB\%curs_attr\fP(3X).
 .PP
 .I curses
-predefines constants for a small set of line-drawing and other graphics
+predefines constants for a small set of forms-drawing graphics
 corresponding to the DEC Alternate Character Set (ACS),
 a feature of VT100 and other terminals.
-See
-\fB\%waddch\fP(3X) and
-\fB\%wadd_wch\fP(3X).
+See \fB\%waddch\fP(3X).
 .PP
 .I curses
 is implemented using the operating system's terminal driver;
@@ -351,6 +353,12 @@ .SS Overview
 translates these into unique
 .I "key codes."
 See \fB\%getch\fP(3X).
+.PP
+.I \%ncurses
+provides reimplementations of the SVr4 \fBpanel\fP(3), \fBform\fP(3),
+and \fBmenu\fP(3X) libraries to ease construction of user interfaces
+with
+.IR curses .
 .SS "Initialization"
 The selection of an appropriate value of
 .I TERM
@@ -373,7 +381,11 @@ .SS "Initialization"
 command.
 See subsection \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
 .PP
-If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set,
+If the environment variables
+.I \%LINES
+and
+.I \%COLUMNS
+are set,
 or if the
 .I curses
 program is executing in a graphical windowing environment,
@@ -384,14 +396,18 @@ .SS "Initialization"
 extension supports resizable terminals;
 see \fB\%wresize\fP(3X).
 .PP
-If the environment variable \fI\%TERMINFO\fP is defined,
+If the environment variable
+.I \%TERMINFO
+is defined,
 a
 .I curses
 program checks first for a terminal type description in the location it
 identifies.
 .I \%TERMINFO
 is useful for developing experimental type descriptions or when write
-permission to \fI\*d\fP is not available.
+permission to
+.I \%\*d
+is not available.
 .PP
 See section \*(``ENVIRONMENT\*('' below.
 .SS "Naming Conventions"
-- 
2.30.2

signature.asc
Description: PGP signature