[PATCH 49/51] man/curs_extend.3x: Revise.

[G. Branden Robinson]

Content:
* Use `bf` as metasyntactic variable name for "Boolean flags", as
  established by ncurses(3X).
* Cross reference terminfo(3X) and termcap(3X) man pages.
* Add "NOTES" section to house admonition against attempting to free(3)
  pointer returned by `curses_version()`, moving that warning from the
  "RETURN VALUE" section.  Cross reference free(3).
* Add introductory sentence to "SEE ALSO" section since, unusually, the
  list of cross referenced pages has no purposeful connection to the
  ones documented here; the idea is to help the reader find man pages
  for other ncurses extensions.

Style:
* Parallelize wording with other man pages documenting ncurses
  extensions.
* Use "that", not "which", with restrictive subordinate clauses.
* Slightly formalize presentation of functions when introducing them,
  using a register more conventional for specification or definition.
* Favor English phrases of Latin abbreviations.
* Set example of `curses_version()` output inline instead of in a
  display.
* Drop period from end of non-sentence.
* Recast.

Markup:
* Protect ncurses function names from hyphenation.
* 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) and terms in the "NAME" section (because the
  generated edit_man.sh script expects font selection escape sequences
  when scraping terms thence to gather names for man page aliases).

* man/man_db.renames.in: Add rewrite rule for "termcap.3x".
---
 man/curs_extend.3x    | 68 +++++++++++++++++++++++++++----------------
 man/man_db.renames.in |  1 +
 2 files changed, 44 insertions(+), 25 deletions(-)

diff --git a/man/curs_extend.3x b/man/curs_extend.3x
index 01cf9d2ec..db9b8f01b 100644
--- a/man/curs_extend.3x
+++ b/man/curs_extend.3x
@@ -50,36 +50,51 @@ .SH SYNOPSIS
 \fB#include <curses.h>
 .PP
 \fBconst char * curses_version(void);
-\fBint use_extended_names(bool \fIenable\fP);
+\fBint use_extended_names(bool \fIbf\fP);
 .fi
 .SH DESCRIPTION
-These functions are extensions to the curses library
-which do not fit easily into other categories.
+These
+.I \%ncurses
+extensions to the
+.I curses
+library do not fit easily into other functional categories.
 .SS curses_version
-Use \fBcurses_version\fP
-to get the version number, including patch level of the library,
-prefixed by \*(``ncurses\*('', e.g.,
-.RS
-.sp
-.B ncurses 5.0.19991023
-.RE
+.B \%curses_version
+returns a pointer to a string containing the library's name
+and version number,
+including its patch level,
+for example
+\*(``ncurses 6.5.20240720\*(''.
 .SS use_extended_names
-The \fBuse_extended_names\fP
-function controls whether the calling application
-is able to use user-defined or nonstandard names
-which may be compiled into the terminfo
-description, i.e., via the terminfo or termcap interfaces.
-Normally these names are available for use, since the essential decision
-is made by using the \fB\-x\fP option of \fB@TIC@\fP to compile
-extended terminal definitions.
-However you can disable this feature
-to ensure compatibility with other implementations of curses.
+.B \%use_extended_names
+configures whether the library recognizes
+user-defined or nonstandard
+.I \%term\%info
+capability names that may be compiled into terminal type descriptions
+via the \fB\%terminfo\fP(3X) or \fB\%termcap\fP(3X) interfaces.
+Normally these names are available for use,
+since the essential decision
+is made through use of \fB\%@TIC@\fP(1)'s
+.B \-x
+option to include such extensions in terminal type descriptions.
+.B \%use_extended_names
+can prevent
+.I \%ncurses
+from recognizing these capabilities
+to ensure compatibility with other implementations of
+.IR curses .
 .SH RETURN VALUE
-\fBcurses_version\fP returns a pointer to static memory; you should not free
-this in your application.
+.B \%curses_version
+returns a constant string.
 .PP
-\fBuse_extended_names\fP returns the previous state, allowing you to
-save this and restore it.
+.B \%use_extended_names
+returns the previous state of extended capability name recognition,
+allowing you to save this property and restore it.
+.SH NOTES
+The pointer returned by
+.B \%curses_version
+corresponds to statically allocated memory;
+do not attempt to \fIfree\fP(3) it.
 .SH EXTENSIONS
 These functions are \fB\%ncurses\fP(3X) extensions,
 and are not found in SVr4
@@ -94,8 +109,11 @@ .SH PORTABILITY
 .B \%NCURSES_VERSION
 preprocessor macro.
 .SH AUTHORS
-Thomas Dickey.
+Thomas Dickey
 .SH SEE ALSO
+.I \%ncurses
+offers several other extensions to the X/Open Curses API.
+.PP
 \fB\%curs_getch\fP(3X),
 \fB\%curs_mouse\fP(3X),
 \fB\%curs_print\fP(3X),
diff --git a/man/man_db.renames.in b/man/man_db.renames.in
index 79fbba2a1..48cfd7567 100644
--- a/man/man_db.renames.in
+++ b/man/man_db.renames.in
@@ -257,6 +257,7 @@ slk_touch.3x                        slk_touch.3ncurses
 start_color.3x                 start_color.3ncurses
 subwin.3x                      subwin.3ncurses
 syncok.3x                      syncok.3ncurses
+termcap.3x                     termcap.3ncurses
 terminfo.3x                    terminfo.3ncurses
 tigetflag.3x                   tigetflag.3ncurses
 tigetstr.3x                    tigetstr.3ncurses
-- 
2.30.2

signature.asc
Description: PGP signature