[PATCH 145/177] man/curs_termattrs.3x: Revise "DESCRIPTION" section.

[G. Branden Robinson]

Content:
* Promote `initscr`, `newterm`, `set_term`, and `setupterm` to man page
  cross references.

Style:
* Favor "line speed" over "baud rate".  Bits per second and baud rate
  have been distinguishable in data communications for a very long time
  now.  (Even _that_ statement concedes too much to the visibility
  of analog encoding methods from contemporary software.)
* Tighten wording.
* Set "curses" in italics, not bold.
* Quote logical operators rather than shouting them.

Markup:
* Define quotation strings in preamble; we need them now.
* Protect literals 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/curs_termattrs.3x | 113 ++++++++++++++++++++++++++++--------------
 1 file changed, 77 insertions(+), 36 deletions(-)

diff --git a/man/curs_termattrs.3x b/man/curs_termattrs.3x
index 700a10319..58c607cea 100644
--- a/man/curs_termattrs.3x
+++ b/man/curs_termattrs.3x
@@ -29,6 +29,16 @@
 .\"
 .\" $Id: curs_termattrs.3x,v 1.44 2024/12/28 21:26:21 tom Exp $
 .TH curs_termattrs 3X 2024-12-28 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" 
"Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
 .SH NAME
 \fB\%baudrate\fP,
 \fB\%erasechar\fP,
@@ -60,55 +70,86 @@ .SH SYNOPSIS
 .fi
 .SH DESCRIPTION
 .SS baudrate
-The \fBbaudrate\fP routine returns the output speed of the terminal.
-The
-number returned is in bits per second, for example \fB9600\fP, and is an
-integer.
+.B \%baudrate
+returns the line speed of the terminal,
+an integer value measured in bits per second,
+for example
+.BR 9600 "."
 .SS "erasechar, erasewchar"
-The \fBerasechar\fP routine returns the user's current erase character.
+.B \%erasechar
+returns the terminal's erase character.
 .PP
-The \fBerasewchar\fP routine stores the current erase character
-in the location referenced by \fIwc\fP.
-If no erase character has been defined, the routine fails
-and the location referenced by \fIwc\fP is not changed.
+.B \%erasewchar
+stores the erase character in the location referenced by
+.IR wc "."
+If no erase character has been defined,
+it fails and the location referenced by
+.I wc
+is not changed.
 .SS "has_ic, has_il"
-The \fBhas_ic\fP routine is true if the terminal has insert- and delete-
-character capabilities.
+.B \%has_ic
+returns
+.B TRUE
+if the terminal has insert- and delete-character capabilities.
 .PP
-The \fBhas_il\fP routine is true if the terminal has insert- and delete-line
-capabilities, or can simulate them using scrolling regions.
-This might
-be used to determine if it would be appropriate to turn on physical
-scrolling using \fBscrollok\fP(3X).
+.B \%has_il
+returns
+.B TRUE
+if the terminal has insert- and delete-line capabilities,
+or can simulate them using scrolling regions.
+It might be used to determine whether it would be appropriate
+to use \fBscrollok\fP(3X) to turn on scrolling.
 .SS "killchar, killwchar"
-The \fBkillchar\fP routine returns the user's current line kill character.
+.B \%killchar
+returns the terminal's line kill character.
 .PP
-The \fBkillwchar\fP routine stores the current line-kill character
-in the location referenced by \fIwc\fP.
+.B \%killwchar
+stores the line-kill character in the location referenced by
+.IR wc "."
 If no line-kill character has been defined,
-the routine fails and the location referenced by \fIwc\fP is not changed.
+it fails and the location referenced by
+.I wc
+is not changed.
 .SS longname
-The \fBlongname\fP routine returns a pointer to a static area
-containing a verbose description of the current terminal.
-The maximum
-length of a verbose description is 128 characters.
-It is defined only
-after the call to \fBinitscr\fP or \fBnewterm\fP.  The area is
-overwritten by each call to \fBnewterm\fP and is not restored by
-\fBset_term\fP, so the value should be saved between calls to
-\fBnewterm\fP if \fBlongname\fP is going to be used with multiple
-terminals.
+.B \%longname
+returns a pointer to static storage
+containing a verbose description of the terminal being managed by
+.IR curses "."
+The maximum length of a verbose description is 128 characters.
+The storage is populated only after \fBinitscr\fP(3X) or
+\fBnewterm\fP(3X) is called.
+This storage is overwritten by each call to
+.B \%newterm
+and not restored by \fBset_term\fP(3X),
+so its contents should be saved between calls to
+.B \%initscr
+or
+.B \%newterm
+if
+.B \%longname
+is to be used with multiple terminals.
 .SS "termattrs, term_attrs"
 If a given terminal does not support a video attribute that an
-application program is trying to use, \fBcurses\fP may substitute a
+application program is trying to use,
+.I curses
+may substitute a
 different video attribute for it.
-The \fBtermattrs\fP and \fBterm_attrs\fP functions
-return a logical \fBOR\fP of all video attributes supported by the
-terminal using \fBA_\fP and \fBWA_\fP constants respectively.
-This information is useful when a \fBcurses\fP program
+.B \%termattrs
+and
+.B \%term_attrs
+return a logical \*(``or\*('' of all video attributes supported by the
+terminal using
+.B A_
+and
+.B WA_
+constants respectively.
+This information is useful when a
+.I curses
+program
 needs complete control over the appearance of the screen.
 .SS termname
-The \fBtermname\fP routine returns the terminal name used by \fBsetupterm\fP.
+.B \%termname
+returns the terminal name used by \fBsetupterm\fP(3X).
 .SH RETURN VALUE
 \fBlongname\fP and \fBtermname\fP return
 .I NULL
-- 
2.30.2

signature.asc
Description: PGP signature