[PATCH 23/52] man/curs_termcap.3x: Fix content and style nits.

[G. Branden Robinson]

Content:
* State the full names of terminal capabilities prior to their less
  scrutable terminfo codes, or their impenetrable termcap ones.
* Fix error: tgetent() (apparently) allocates memory based on the
  uniqueness of the parameters it's given, not the uniqueness of TERM
  environment variable contents when it is called.
* Fix error: Since ncurses 1.8.7 (at the latest), this page has referred
  to a termcap code "ca".  This does not seem to exist.  Change it to
  "ch", which refers to a parameterized capability and makes the same
  point.
* Remind reader where tgetent()'s actual return values can be found when
  discussing the issue in the "PORTABILITY" section.

Style:
* Drop unnecessary colon before a dispayed portion of a sentence.
* Fix missing words.
* Favor active voice over passive.
* Favor present tense over past, when discussing the content of
  standards documents (even old ones).
* Set non-ncurses man page cross reference in italics, not bold.

Markup:
* Adjust tag widths used for tgetent() return values so that they set
  without ugly breaks.
---
 man/curs_termcap.3x | 51 +++++++++++++++++++++++++--------------------
 1 file changed, 28 insertions(+), 23 deletions(-)

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index 721dbb126..eace0e033 100644
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -87,12 +87,12 @@ .SS Initialization
 \fB\%tgetent\fP loads the terminal database entry for \fIname\fP;
 see \fBterm\fP(7).
 This must be done before calling any of the other functions.
-It returns:
+It returns
 .RS 3
-.TP 4
+.TP 5 \" "-1" + 2n + adjust for PDF
 1
 on success,
-.TP 4
+.TP
 0
 if there is no such entry
 (or if the matching entry describes a generic terminal,
@@ -100,7 +100,7 @@ .SS Initialization
 .I curses
 applications to run),
 and
-.TP 4
+.TP
 \-1
 if the \fI\%term\%info\fP database could not be found.
 .RE
@@ -120,9 +120,9 @@ .SS Initialization
 .bP
 The meanings of the return values differ.
 The BSD \fItermcap\fP library does not check whether the terminal type
-description is marked with the
-.B gn
-.RB ( \%generic )
+description includes the
+.B \%generic
+.RB ( gn )
 capability,
 nor whether the terminal type description supports an addressable
 cursor,
@@ -189,7 +189,7 @@ .SS "Applying String Capabilities"
 most hardware terminals use cursor addressing with \fIrow\fP first,
 but the original developers of the \fItermcap\fP interface chose to
 put the \fIcol\fP (column) parameter first.
-The \fB\%tgoto\fP function swaps the order of parameters.
+The \fB\%tgoto\fP function swaps the order of its parameters.
 It does this even for calls requiring only a single parameter.
 In that case,
 the first parameter is merely a placeholder.
@@ -249,9 +249,8 @@ .SS "Releasing Memory"
 to free this memory,
 but there is an additional complication with \fI\%ncurses\fP.
 It uses a fixed-size pool of storage locations,
-one per value of the \fITERM\fP environment variable when
-\fB\%tgetent\fP is called.
-The \fBscreen\fP(1) program relies upon this arrangement to improve its
+one per value of the terminal name parameter given to \fB\%tgetent\fP.
+The \fIscreen\fP(1) program relies upon this arrangement to improve its
 performance.
 .PP
 An application that uses only the \fItermcap\fP functions,
@@ -308,17 +307,16 @@ .SH PORTABILITY
 .SS Standards
 .bP
 X/Open Curses, Issue 4, Version 2 (1996),
-describes these functions.
-However,
-they are marked
+describes these functions,
+marking them as
 \*(``TO BE WITHDRAWN\*(''.
 .bP
-X/Open Curses, Issue 7 (2009) marked the \fItermcap\fP interface
+X/Open Curses, Issue 7 (2009) marks the \fItermcap\fP interface
 (along with \fB\%vwprintw\fP and \fB\%vwscanw\fP) as withdrawn.
 .PP
 Neither X/Open Curses nor the SVr4 man pages documented the return
 values of \fB\%tgetent\fP correctly,
-though all three were in fact returned ever since SVr1.
+though all three shown here were in fact returned ever since SVr1.
 In particular,
 an omission in the X/Open Curses specification has been misinterpreted
 to mean that \fB\%tgetent\fP returns \fBOK\fP or \fBERR\fP.
@@ -416,8 +414,8 @@ .SH HISTORY
 .\" entry points disappearing from termcap.c.
 but left the API unchanged.
 .PP
-Function prototypes were a feature of the forthcoming ANSI C (1989).
-Thus the library provided no header file declaring them.
+Function prototypes were a feature of ANSI C (1989).
+Thus the library itself provided no header file declaring them.
 Nevertheless,
 the BSD sources included two different \fI\%termcap.h\fP header files
 over time.
@@ -486,8 +484,10 @@ .SH HISTORY
 and programs that intend to work with all \fItermcap\fP library
 interfaces must account for that fact.
 .SH BUGS
-If you call \fB\%tgetstr\fP to fetch \fB\%ca\fP or any other
-parameterized string capability,
+If you call \fB\%tgetstr\fP to fetch
+.B \%column_address
+.RB ( ch )
+or any other parameterized string capability,
 be aware that it is returned in \fI\%term\%info\fP notation,
 not the older and not-quite-compatible \fItermcap\fP notation.
 This does not cause problems if all you do with it is call \fB\%tgoto\fP
@@ -521,11 +521,16 @@ .SH BUGS
 \fB\%tputs("50")\fP in a \fItermcap\fP system may busy-wait for 50
 milliseconds rather than transmitting \*(``50\*(''.
 .PP
-\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's \fBsgr\fP
-string.
+\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's
+.B \%set_attributes
+.RB ( sgr )
+capability.
 One consequence is that \fItermcap\fP applications assume that
 .RB \*(`` me \*(''
-(equivalent to \fI\%term\%info\fP's \fBsgr0\fP capability)
+(equivalent to \fI\%term\%info\fP's
+.B \%exit_attribute_mode
+.RB ( sgr0 )
+capability)
 does not reset the alternate character set.
 \fI\%ncurses\fP checks for,
 and modifies the data shared with,
-- 
2.30.2

signature.asc
Description: PGP signature