[PATCH 152/177] man/curs_termcap.3x: Revise "SYNOPSIS" and "DESCRIPTION" sections.

[G. Branden Robinson]

Content:
* Refer to the user-supplied storage referred to by `tgetstr()`'s second
  argument as a "buffer", not an "area", and rename its formal argument
  from `area` to `sbuf`.  I find the "buffer" usage less vague.
* When naming a capability ("long name" or C symbol), also indicate its
  cap-code in parentheses.

Style:
* Stop applying an inset to a bulleted list; other ncurses man pages
  presenting similarly structured material don't seem to do this.  (See,
  e.g., clear(1): "HISTORY"; infocmp(1): "Changing Databases ...", "-q",
  "-Rsubset", "HISTORY"; tabs(1): "PORTABILITY"; tic(1): "DESCRIPTION",
  "EXTENSIONS", toe(1): "HISTORY"; tput(1): "PORTABILITY", "HISTORY";
  tset(1): "tset -- initialization", "reset -- reinitialization",
  "PORTABILITY", add_wch(3X): "wadd_wch", "RETURN VALUE", "PORTABILITY",
  "Complex Characters", ...
* Hyphenate attributive phrase.
---
 man/curs_termcap.3x | 66 ++++++++++++++++++++++++++-------------------
 1 file changed, 39 insertions(+), 27 deletions(-)

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index 1001e3b9c..14b0a9d5d 100644
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -118,7 +118,7 @@ .SH SYNOPSIS
 \fBint tgetent(char * \fIbp\fP, const char * \fIname\fP);
 \fBint tgetflag(const char * \fIid\fP);
 \fBint tgetnum(const char * \fIid\fP);
-\fBchar * tgetstr(const char * \fIid\fP, char ** \fIarea\fP);
+\fBchar * tgetstr(const char * \fIid\fP, char ** \fIsbuf\fP);
 \fBchar * tgoto(const char * \fIcap\fP, int \fIcol\fP, int \fIrow\fP);
 \fBint tputs(const char * \fIstr\fP, int \fIaffcnt\fP, int (* 
\fIputc\fP)(int));
 .fi
@@ -157,14 +157,13 @@ .SS Initialization
 .PP
 This implementation differs from those of historical \fItermcap\fP
 libraries.
-.RS 3
 .bP
 .I \%ncurses
 ignores the buffer pointer \fIbp\fP,
 as do other \fItermcap\fP implementations conforming to portions of
 X/Open Curses now withdrawn.
 The BSD \fItermcap\fP library would store a copy of the terminal type
-description in the area referenced by this pointer.
+description in the buffer referenced by this pointer.
 \fI\%term\%info\fP stores terminal type descriptions in compiled form,
 which is not the same thing.
 .bP
@@ -177,7 +176,6 @@ .SS Initialization
 nor whether the terminal type description supports an addressable
 cursor,
 a property essential for any \fIcurses\fP implementation to operate.
-.RE
 .SS "Retrieving Capability Values"
 \fB\%tgetflag\fP reports the Boolean entry for \fIid\fP,
 or zero if it is not available.
@@ -191,34 +189,36 @@ .SS "Retrieving Capability Values"
 if it is not available.
 Use \fB\%tputs\fP to output the string returned.
 The
-.I area
+.I sbuf
 parameter is used as follows.
-.RS 3
 .bP
 It is assumed to be the address of a pointer to a buffer managed by the
 calling application.
 .bP
 However,
-\fI\%ncurses\fP checks to ensure that
-.I area
+.I \%ncurses
+checks to ensure that
+.I sbuf
 is not
 .IR NULL ","
-and also that the resulting buffer pointer is not
+and that the pointer obtained by dereferencing
+.I sbuf
+is also not
 .IR NULL "."
 If either check fails,
-.I area
-is ignored.
+.I \%ncurses
+ignores
+.IR sbuf .
 .bP
 If the checks succeed,
 \fI\%ncurses\fP also copies the return value to the buffer pointed to by
-\fIarea\fP,
+\fIsbuf\fP,
 and the library updates
-.I area
+.I sbuf
 to point past the null character terminating this value.
 .bP
 The return value itself is an address in the terminal type description
 loaded into memory.
-.RE
 .SS "Applying String Capabilities"
 String capabilities can be parameterized;
 see subsection \*(``Parameterized Strings\*('' in  \fB\%terminfo\fP(5).
@@ -275,27 +275,39 @@ .SS "Global Variables"
 to the
 .I \%term\%info
 entry's data for
-.BR \%pad_char ","
-.BR \%cursor_up ","
+.B \%pad_char
+.RB ( pad ),
+.B \%cursor_up
+.RB ( cuu1 ),
 and
-.BR \%backspace_if_not_bs ","
+.B \%backspace_if_not_bs
+.RB ( OTbs ),
 respectively.
-\fBUP\fP is not used by
-.IR \%ncurses "."
-.B PC
-is used by \fB\%delay_output\fP(3X).
-.B BC
-is used by
+.I \%ncurses
+does not employ
+.B cuu1
+internally.
+\fB\%delay_output\fP(3X)
+uses
+.BR pad ","
+while
 .B \%tgoto
-emulation.
+emulation uses the obsolete
+.I termcap
+capability
+.BR bs ","
+represented in
+.I \%ncurses
+.I \%term\%info
+as \*(``OTbs\*(''.
 .I \%ncurses
 assigns the variable
 .B \%ospeed
 a system-specific value to encode the terminal's data rate.
 .SS "Releasing Memory"
 The \fItermcap\fP functions provide no means of freeing memory,
-because legacy \fItermcap\fP implementations used only the buffer
-areas provided by the caller via \fB\%tgetent\fP and \fB\%tgetstr\fP.
+because legacy \fItermcap\fP implementations used only the storage
+provided by the caller via \fB\%tgetent\fP and \fB\%tgetstr\fP.
 Those buffers are unused in \fI\%term\%info\fP.
 .PP
 By contrast,
@@ -316,7 +328,7 @@ .SS "Releasing Memory"
 performance.
 .PP
 An application that uses only the \fItermcap\fP functions,
-not the higher level
+not the higher-level
 .I \%curses
 API,
 could release the memory using \fB\%del_curterm\fP(3X),
-- 
2.30.2

signature.asc
Description: PGP signature