[PATCH 4/5] man/captoinfo.1m: Revise.

[G. Branden Robinson]

* Define more attractive and useful strings for rendering double quotes.
  If the formatter claims groff compatibility (sets the `.g` register),
  define the `` and '' strings to the `lq` and `rq` special characters,
  respectively.

  Otherwise, if a typesetter is being used (the `t` condition is true),
  use the existing fallback of "``" and "''" character sequences, which
  troff implementations map to (repeated) directional single quotes.

  Otherwise, a non-groff-compatible nroff is in use: define both strings
  to interpolate ", a.k.a. U+0022, a non-directional double quote.
  Doing this requires knowledge of a detail of the `ds` *roff request: a
  leading double quote is removed, permitting a string's contents to
  begin with leading spaces (or tabs).  Thereafter, double quotes are
  treated literally.

  Tested with groff, mandoc, Heirloom Doctools nroff and troff, and
  Documenter's Workbench (DWB) 3.3 nroff and troff.

* Mark "file" arguments as optional in synopsis.

* Convert alternative synopsis (for "captoinfo -V") to call man(7)
  macros for formatting.

* Protect boldfaced literals from hyphenation.

* Use active voice more.

* Increase precision of discussion.  For instance, speak of standard I/O
  streams more explicitly, by reference to the concept instead of C
  standard library symbol names.  As another example, an environment
  variable's name is not the same thing as its contents, and should not
  be discussed as if it is.  A third: talking about "IBM PC high-half
  graphics" in reference to CCSID (code page) 437.  We can do better
  than the dissipated and slovenly discourse of Unix terminal rooms of
  the past, where code cowboys jockeyed for status with the hermeticism
  of their utterances.

* Quote a literal in addition to boldfacing it where it is an English
  word that might confuse the reader when font style formatting is
  stripped (e.g., when copy-and-pasting from the man page).

* Set subsection heading in sentence case, floating a modest reform from
  the groff and Linux man-pages projects.

* Unabbreviate column headings in nonstandard termcap capability table;
  it still fits in the 65 columns used by DWB 3.3 nroff.

* Set "terminfo" in bold italics in a column heading.  Caveat: this
  selection isn't _perfectly_ portable--it may not work on Seventh
  Edition Unix (1979; where curses didn't exist anyway), and will fail
  to effect a style change on devices where the selected font family
  lacks a heavy slanted face.  I expect this to be a problem only in
  perverse circumstances involving typesetter usage and user-directed,
  non-default font selections; it shouldn't mess up any nroff formatter
  ("mandoc | less" works fine).  But at worst the problem should be a
  cosmetic one.

  Tested with groff, mandoc, Heirloom Doctools nroff and troff, and
  Documenter's Workbench (DWB) 3.3 nroff and troff.  Heirloom and DWB
  troffs produce the desired output on their Postscript devices
  (dpost(1)).  Heirloom and DWB nroffs assume a terminal capable of
  overstriking (like Western Electric Teletype Model 37), so what you
  get depends on what you pipe its output through, and/or your terminal
  emulator's behavior.  Piping through util-linux's ul(1) produces
  normal-weight inverse video for bold italics for me on xterm(1), with
  or without piping through "less -R".  Piping DWB nroff output
  _without_ ul(1) through "less" (_without_ -R) renders the bold italics
  fine (as underlined bold) but has other problems with tables as I
  mentioned in
  <https://lists.gnu.org/archive/html/bug-ncurses/2023-09/msg00006.html>.

* Center the columns of termcap capability names in the table.

* Refer to XENIX in the past tense; it seems to be a dead product.

* Set capability name column in bold in XENIX table.

* Improve descriptions of graphics corresponding to XENIX capabilities.

* Capitalize "ACS" (presumably a DEC reference?).

* Annotate open questions about this XENIX table in comments.

* Speak less of the tool doing things "automatically"; that is the
  point of implementing it.  (More puffery from the terminal room?)

* Stop using colons followed by tables (or other displays) as excuses
  not to punctuate sentence endings.

* Set capability names in bold, not italics ("box1").

* Speak of the product ("HP-UX") not the vendor (Hewlett-Packard).  See
  <https://docstore.mik.ua/manuals/hp-ux/en/B2355-60130/terminfo.4.html>.

* Drop explicit indentation from `TP` call in "FILES" section.  The
  ncurses man pages seem to follow no consistent format here (cf.
  infocmp.1m, ncurses.3x, panel.3x, term.5, and terminfo.tail, each
  taking a different approach).  I choose the simplest.

* Set file names in italics.  Again, the ncurses man pages follow no
  consistent convention.

* Set metasyntactic variable "n" in italics.

* Add cross reference to tic(1M) in "SEE ALSO" section.
---
 man/captoinfo.1m | 164 ++++++++++++++++++++++++++---------------------
 1 file changed, 92 insertions(+), 72 deletions(-)

diff --git a/man/captoinfo.1m b/man/captoinfo.1m
index bba8a616..a04a9c7c 100644
--- a/man/captoinfo.1m
+++ b/man/captoinfo.1m
@@ -30,6 +30,16 @@
 .\"
 .\" $Id: captoinfo.1m,v 1.44 2023/09/16 23:39:05 tom Exp $
 .TH @CAPTOINFO@ 1M 2023-09-16 "ncurses 6.4" "User commands"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
 .ds n 5
 .ds d /etc/termcap
 .SH NAME
@@ -38,51 +48,51 @@ .SH NAME
 .SH SYNOPSIS
 .B @CAPTOINFO@
 .RI [ tic-option ]
-.I file
-\&.\|.\|.
+.RI [ file
+\&.\|.\|.]
 .P
-\fB@CAPTOINFO@\fR \fB\-V\fR
+.B "@CAPTOINFO@ \-V"
 .SH DESCRIPTION
-\fB@CAPTOINFO@\fP looks in each given text
-\fIfile\fP for \fBtermcap\fP descriptions.
-For each
-one found, an equivalent \fBterminfo\fP description is written to standard
-output.
-Termcap \fBtc\fP capabilities are translated directly to terminfo
-\fBuse\fP capabilities.
+\fB\%@CAPTOINFO@\fP looks in each given text
+\fIfile\fP for \fItermcap\fP descriptions.
+For each one found,
+it writes an equivalent \fIterminfo\fP description to the standard
+output stream.
+\fItermcap\fP \fBtc\fP capabilities are translated directly to
+\fIterminfo\fP \*(``\fBuse\fP\*('' capabilities.
 .PP
-If no \fIfile\fP is given, then the environment variable \fBTERMCAP\fP is used
-for the filename or entry.
-If \fBTERMCAP\fP is a full pathname to a file, only
-the terminal whose name is specified in the environment variable \fBTERM\fP is
-extracted from that file.
-If the environment variable \fBTERMCAP\fP is not
-set, then the file \fB\*d\fP is read.
+If no \fIfile\fPs are specified,
+\fB\%@CAPTOINFO@\fP interprets the content of the environment variable
+\fB\%TERMCAP\fP as a file name,
+and extracts only the entry for the terminal named in the environment
+variable \fB\%TERM\fP from it.
+If the environment variable \fB\%TERMCAP\fP is not set,
+\fB\%@CAPTOINFO@\fP reads \fI\%\*d\fP.
 .PP
-This utility is implemented as a link to \fB@TIC@\fP(1M),
+This utility is implemented as a link to \fB\%@TIC@\fP(1M),
 with the latter's
 .B \-I
 option implied.
-You can use other \fB@TIC@\fP options such as
+You can use other \fB\%@TIC@\fP options such as
 .BR \-1 ,
 .BR \-f ,
 .BR \-v ,
 .BR \-w ,
 and
 .BR \-x .
-.SH TRANSLATIONS FROM NONSTANDARD CAPABILITIES
-Some obsolete nonstandard capabilities will automatically be translated
-into standard (SVr4/XSI Curses) terminfo capabilities by \fB@CAPTOINFO@\fP.
-Whenever one of these automatic translations is done, the program
-will issue an notification to stderr, inviting the user to check that
-it has not mistakenly translated a completely unknown and random
-capability and/or syntax error.
+.SS "Translations from nonstandard capabilities"
+\fB\%@CAPTOINFO@\fP translates some obsolete,
+nonstandard capabilities into standard (SVr4/XSI Curses) \fIterminfo\fP
+capabilities.
+It issues a diagnostic to the standard error stream for each,
+inviting the user to check that it has not mistakenly translated an
+unknown or mistyped capability name.
 .PP
 .TS
 cb cb cb cb
 cb cb cb cb
-l  l  l  l .
-Nonstd Std     \&      Terminfo
+cb cb l  lb.
+Nonstandard    Standard        \&      \f(BIterminfo\fP
 name   name    From    capability
 _
 BO     mr      AT&T    enter_reverse_mode
@@ -115,50 +125,55 @@ .SH TRANSLATIONS FROM NONSTANDARD CAPABILITIES
 HS     mh      Iris    enter_dim_mode
 .TE
 .PP
-XENIX termcap also used to have a set of extension capabilities
-for forms drawing, designed to take advantage of the IBM PC
-high-half graphics.
-They were as follows:
+XENIX \fItermcap\fP had a set of extension capabilities,
+corresponding to box drawing characters of CCSID
+(\*(``code page\*('') 437,
+as follows.
 .PP
 .TS
 cb cb
-l l.
+lb l .
 Cap    Graphic
 _
-G2     upper left
-G3     lower left
-G1     upper right
-G4     lower right
-GR     pointing right
-GL     pointing left
-GU     pointing up
-GD     pointing down
+G2     upper left corner
+G3     lower left corner
+G1     upper right corner
+G4     lower right corner
+GR     tee pointing right
+GL     tee pointing left
+GU     tee pointing up
+GD     tee pointing down
 GH     horizontal line
 GV     vertical line
 GC     intersection
-G6     upper left
-G7     lower left
-G5     upper right
-G8     lower right
-Gr     tee pointing right
-Gr     tee pointing left
-Gu     tee pointing up
-Gd     tee pointing down
-Gh     horizontal line
-Gv     vertical line
-Gc     intersection
-GG     acs magic cookie count
+G6     double upper left corner
+G7     double lower left corner
+G5     double upper right corner
+G8     double lower right corner
+Gr     double tee pointing right
+Gr     double tee pointing left
+Gu     double tee pointing up
+Gd     double tee pointing down
+Gh     double horizontal line
+Gv     double vertical line
+Gc     double intersection
+.\" TODO: There are about 40 box drawing code points in CCSID 437;
+.\" were there no XENIX capabilities for the mixed single- and double-
+.\" line intersections?
+.\"
+.\" TODO: GG doesn't seem to fit with the others; explain it.
+GG     ACS magic cookie count
 .TE
 .PP
-If the single-line capabilities occur in an entry, they will automatically
-be composed into an \fBacsc\fP string.
+If the single-line capabilities occur in an entry,
+they are composed into an \fBacsc\fP string.
 The double-line capabilities and
 \fBGG\fP are discarded with a warning message.
 .PP
-IBM's AIX has a terminfo facility descended from SVr1 terminfo but incompatible
-with the SVr4 format.
-The following AIX extensions are automatically
-translated:
+IBM's AIX has a \fIterminfo\fP facility descended from SVr1
+\fIterminfo\fP,
+but which is incompatible with the SVr4 format.
+\fB\%@CAPTOINFO@\fP translates the following AIX extensions.
 .PP
 .TS
 cb cb
@@ -173,32 +188,37 @@ .SH TRANSLATIONS FROM NONSTANDARD CAPABILITIES
 font3  s3ds
 .TE
 .PP
-Additionally, the AIX \fIbox1\fP capability will be automatically translated to
-an \fBacsc\fP string.
+Additionally,
+this program translates the AIX \fBbox1\fP capability to an \fBacsc\fP
+string.
 .PP
-Hewlett-Packard's terminfo library supports two nonstandard terminfo
-capabilities \fBmeml\fP (memory lock) and \fBmemu\fP (memory unlock).
-These will be discarded with a warning message.
+The HP-UX \fIterminfo\fP library supports two nonstandard \fIterminfo\fP
+capabilities,
+\fBmeml\fP (memory lock) and \fBmemu\fP (memory unlock).
+\fB\%@CAPTOINFO@\fP discards these with a warning message.
 .SH FILES
-.TP 20
-\*d
+.TP
+\fI\*d\fP
 default \fItermcap\fP terminal capability database
 .SH NOTES
 The verbose option is not identical to SVr4's.
 Under SVr4, instead of following
-the \fB\-v\fP with a trace level n, you repeat it n times.
+the \fB\-v\fP with a trace level \fIn\fP,
+you repeat it \fIn\fP times.
 .SH PORTABILITY
 X/Open Curses, Issue 7 (2009) describes \fBtic\fP briefly,
 but omits this program.
-SVr4 systems provide \fBcaptoinfo\fP as a separate application from \fBtic\fP.
+SVr4 systems provide \fB\%captoinfo\fP as a separate application from
+\fBtic\fP.
 .PP
 NetBSD does not provide this application.
 .SH SEE ALSO
-\fB@INFOCMP@\fP(1M),
-\fBcurses\fP(3X),
-\fBterminfo\fP(\*n)
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(\*n)
 .PP
-This describes \fBncurses\fP
+This describes \fIncurses\fP
 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
 .SH AUTHOR
 Eric S. Raymond <esr@snark.thyrsus.com>
-- 
2.30.2

signature.asc
Description: PGP signature