[PATCH] man pages: Access monospaced font more portably.

[G. Branden Robinson]

It is futile to attempt changes of font family on terminals, and
unnecessary besides; character-cell terminal fonts are already
monospaced.[1]  There is no guaranteed portable typeface name to obtain
a monospaced font in typesetter roff (troff), either; device-independent
troff, developed by Kernighan ca. 1980, decided that font repertoires
(like special character identifiers) were hopelessly device-specific.
Unix System III promptly introduced a "CW" face and tools to use it,
like checkcw(1), but the troff in BSD Unix never shipped or supported
these.  Later in the 1980s, Adobe PostScript introduced a set of 14
"standard" fonts that any compliant device was expected (perhaps legally
required to support): these included the monospaced Courier family in
roman (upright), italic (oblique), bold, and bold-italic styles.  AT&T
Documenter's Workbench troff supported a "post" device that recognized
the "CW" name for backward compatibility, along with a variety of names
for accessing the individual styles: "C", "CO", "CI", "CB", "CX".  At
least some of these names made it back into USG troff (later, System V
Unix)  and Research Unix troff (maintained by Kernighan).  Again, none
of these developments were reflected in BSD troff.

In 1989-1991, James Clark's groff generalized Adobe's standard font
scheme into a family/style naming convention, and discarded AT&T troff's
limitation of font names to two characters.[2]  Thus, for 32+ years
groff has supported the face names "CR", "CI", "CB", and "CBI"
everywhere the underlying device offers a suitable monospaced family
(its "dvi" and "lbp" devices do not).

BSD Unix Networking Release/2 ("Net/2") (1991) discarded its
pre-device-independent troff from Unix Version 7 (1979) for groff.  Most
descendants of BSD have since thrown groff over in favor of mandoc(1),
initially developed as "mdocml" in 2008 for the purpose of generating
HTML from mdoc(7) documents, and which has ruled general purpose
typesetting out of its scope.  It recognizes the groff font names
mentioned above, but its support for the bold-italic style is
limited--for terminal output, what you get is up to what interprets
mandoc's overstriking output sequences (your pager, terminal emulator,
or ul(1)), and for HTML output, the bold-italic style is unavailable in
a monospaced context.

In groff 1.23.0 (2023), GNU troff started issuing warnings if futile
font selections are attempted.

Consequently...

* man/MKada_config.in:
* man/ncurses.3x:
* man/term.5:
* man/term_variables.3x:
* man/terminfo.head: Define a string `CW` to store the name of the
  desired monospaced font; in nroff mode (which mandoc(1) claims to
  use), this simply the roman face "R".  In troff mode, if the formatter
  claims groff compatibility, use face "CR".  Otherwise, use face "CW".

* man/MKada_config.in:
* man/ncurses.3x:
* man/term.5:
* man/term_variables.3x:
* man/terminfo.head:
* man/terminfo.tail: Interpolate the `CW` string instead of explicitly
  selecting the "CW" typeface.

[1] ...impracticalities like "xterm -fn variable" aside.

[2] This limitation may be overstated in popular conception; I don't
    have a copy of Research Unix troff to test my hypothesis on, but the
    1992 revision of CSTR #54 by Kernighan suggests to me that one could
    use the 3-argument form of the `fp` request to "register" a font
    "alias" using an arbitrarily long name, and then select that name
    with the `ft` request.  There was still no evident syntax for
    selection of long font names via an escape sequence however, which
    is far and away the preference of the Cargo Cult school of man page
    authorship.
---
 man/MKada_config.in   | 11 ++++++++---
 man/ncurses.3x        |  9 +++++++--
 man/term.5            |  9 +++++++--
 man/term_variables.3x |  7 ++++++-
 man/terminfo.head     |  7 ++++++-
 man/terminfo.tail     | 10 +++++-----
 6 files changed, 39 insertions(+), 14 deletions(-)

diff --git a/man/MKada_config.in b/man/MKada_config.in
index 3a2986fa..2eae29a5 100644
--- a/man/MKada_config.in
+++ b/man/MKada_config.in
@@ -30,6 +30,11 @@
 .\" $Id: MKada_config.in,v 1.16 2023/08/19 19:12:34 tom Exp $
 .ds C adacurses@USE_CFG_SUFFIX@\-config
 .TH ADACURSES 1 2023-08-19 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User 
commands"
+.ie n .ds CW R
+.el   \{
+.ie \n(.g .ds CW CR
+.el       .ds CW CW
+.\}
 .SH NAME
 adacurses@USE_CFG_SUFFIX@\-config \- helper script for @ADA_LIBNAME@ libraries
 .SH SYNOPSIS
@@ -64,7 +69,7 @@ program for @ADA_LIBNAME@.
 Make a file named "hello.adb":
 .RS
 .nf
-.ft CW
+.ft \*(CW
 with Terminal_Interface.Curses; use Terminal_Interface.Curses;
 
 procedure Hello is
@@ -103,14 +108,14 @@ end Hello;
 .PP
 Then, using
 .RS
-.ft CW
+.ft \*(CW
 gnatmake `adacurses-config --cflags` hello -largs `adacurses-config --libs`
 .ft
 .RE
 .PP
 or (simpler):
 .RS
-.ft CW
+.ft \*(CW
 gnatmake hello `adacurses-config`
 .ft
 .RE
diff --git a/man/ncurses.3x b/man/ncurses.3x
index 86361f9b..87009e7e 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -35,6 +35,11 @@
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
+.ie n .ds CW R
+.el   \{
+.ie \n(.g .ds CW CR
+.el       .ds CW CW
+.\}
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
@@ -45,7 +50,7 @@
 .ie n  .in +4
 .el    .in +2
 .nf
-.ft CR                 \" Courier
+.ft \*(CW
 ..
 .de NE
 .fi
@@ -1036,7 +1041,7 @@ .SS NCURSES_NO_UTF8_ACS
 This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
 For example
 .RS 3
-.ft CW
+.ft \*(CW
 .sp
 .nf
 # linux console, if patched to provide working
diff --git a/man/term.5 b/man/term.5
index 629358d6..62c90a18 100644
--- a/man/term.5
+++ b/man/term.5
@@ -33,13 +33,18 @@
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
+.ie n .ds CW R
+.el   \{
+.ie \n(.g .ds CW CR
+.el       .ds CW CW
+.\}
 .de NS
 .ie n  .sp
 .el    .sp .5
 .ie n  .in +4
 .el    .in +2
 .nf
-.ft CR                 \" Courier
+.ft \*(CW
 ..
 .de NE
 .fi
@@ -357,7 +362,7 @@ .SH EXAMPLE
 .ie n .in -2n
 .el   .in +4n
 .TS
-lp-1f(CW).
+lp-1f(\*(CW).
 0000  1a 01 10 00 02 00 03 00  82 00 31 00 61 64 6d 33  ........ ..1.adm3
 0010  61 7c 6c 73 69 20 61 64  6d 33 61 00 00 01 50 00  a|lsi ad m3a...P.
 0020  ff ff 18 00 ff ff 00 00  02 00 ff ff ff ff 04 00  ........ ........
diff --git a/man/term_variables.3x b/man/term_variables.3x
index 76dc5347..c40a3f6b 100644
--- a/man/term_variables.3x
+++ b/man/term_variables.3x
@@ -34,6 +34,11 @@
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
+.ie n .ds CW R
+.el   \{
+.ie \n(.g .ds CW CR
+.el       .ds CW CW
+.\}
 .na
 .hy 0
 .SH NAME
@@ -152,7 +157,7 @@ .SS Terminfo Names
 which is defined
 .PP
 .nf
-.ft CW
+.ft \*(CW
 #define CUR ((TERMTYPE *)(cur_term))->
 .fi
 .ft R
diff --git a/man/terminfo.head b/man/terminfo.head
index 6e7fad48..5f7ba028 100644
--- a/man/terminfo.head
+++ b/man/terminfo.head
@@ -39,6 +39,11 @@
 .el       .ds ^ ^
 .ie \n(.g .ds ~ \(ti
 .el       .ds ~ ~
+.ie n .ds CW R
+.el   \{
+.ie \n(.g .ds CW CR
+.el       .ds CW CW
+.\}
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
@@ -49,7 +54,7 @@
 .ie n  .in +4
 .el    .in +2
 .nf
-.ft C                  \" Courier
+.ft \*(CW
 ..
 .de NE
 .fi
diff --git a/man/terminfo.tail b/man/terminfo.tail
index 62b757e1..c9472cbb 100644
--- a/man/terminfo.tail
+++ b/man/terminfo.tail
@@ -85,7 +85,7 @@ The following entry, describing an ANSI-standard terminal, is 
representative
 of what a \fBterminfo\fP entry for a modern terminal typically looks like.
 .PP
 .nf
-.ft CW
+.ft \*(CW
 \s-2ansi|ansi/pc-term compatible with color,
         am, mc5i, mir, msgr,
         colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64,
@@ -434,7 +434,7 @@ Thus the model 33 teletype is described as
 .PP
 .DT
 .nf
-.ft CW
+.ft \*(CW
 .\".in -2
 \s-133\||\|tty33\||\|tty\||\|model 33 teletype,
         bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
@@ -446,7 +446,7 @@ while the Lear Siegler \s-1ADM-3\s0 is described as
 .PP
 .DT
 .nf
-.ft CW
+.ft \*(CW
 .\".in -2
 \s-1adm3\||\|3\||\|lsi adm3,
         am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
@@ -488,7 +488,7 @@ as in \fBprintf\fP(3), flags are \fI[\-+#]\fP and 
\fIspace\fP.
 Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag,
 avoiding interpreting \*(``%\-\*('' as an operator.
 .TP
-\f(CW%c\fP
+\f\*(CW%c\fP
 print \fIpop()\fP like %c in \fBprintf\fP
 .TP
 \fB%s\fP
@@ -1137,7 +1137,7 @@ m always  m
 .PP
 Putting this all together into the sgr sequence gives:
 .PP
-.ft CW
+.ft \*(CW
 .nf
     sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
         %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;,
-- 
2.30.2

signature.asc
Description: PGP signature