Non-portable font C

[paravoid]

This snippet:

# OPTIONS

`--help`

:   Show the help message.

With newer versions of groff, as they exist now in Debian unstable, emits these warnings:

$ groff --version
GNU groff version 1.23.0
Copyright (C) 2022 Free Software Foundation, Inc.
GNU groff comes with ABSOLUTELY NO WARRANTY.
You may redistribute copies of groff and its subprograms
under the terms of the GNU General Public License.
For more information about these matters, see the file
named COPYING.

called subprograms:

GNU troff (groff) version 1.23.0
GNU grops (groff) version 1.23.0

$ lowdown -s -Tman -M title:TEST -M section:1 -Mdate:$(date -I -u) test.md | groff -Tascii -man >/dev/null 
troff:<standard input>:6: warning: cannot select font 'C'

Note that mandoc is also unhappy:

$ lowdown -s -Tman -M title:TEST -M section:1 -Mdate:$(date -I -u) test.md | mandoc -T lint
mandoc: <stdin>:6:1: WARNING: invalid escape sequence: \fC
mandoc: <stdin>:5:2: WARNING: skipping paragraph macro: PP after SH

Debian bug #1041809 against rst2man, exhibiting similar behavior, provides some additional context.

[paravoid]

Debian bug #1043256 has even more context.

[kristapsdz]

Hi faidon. This is a tricky one... can you keep an eye on these commits and see if they work for you?

pandoc uses an .ie clause in the header and uses a custom V font, which doesn't play well with mandoc. My solution is to use B (bold font) for -tman and C (constant-width) for -tms by default. The user can override this with --nroff-code-font, which I've not yet finalised upon or documented. (Later commits wihle I ruminate.)

This, I think, sets some useful defaults while letting the user override the output, playing reasonably well with groff and mandoc.

[g-branden-robinson]

Thomas Dickey recently merged changes from me to his ncurses man pages that look like this.

.ie n .ds CW R
.el   \{
.ie \n(.g .ds CW CR
.el       .ds CW CW
.\}

.ft \*(CW

This defines a roff string named "CW". Translated to English, this means...

• If formatting for a terminal (that is, "in nroff mode"), define the string as "R" (the roman style--always available).
• Otherwise, we are formatting for a typesetter.
  • If the formatter claims groff compatibility, use the font name "CR" ("Courier roman").
  • Otherwise, use the font name "CW" ("constant-width", from Unix System III troff and later).
• There has not been such a thing as BSD troff since before Networking Release/2 (1991), before the CSRG disbanded. (When there was, it was descended from Seventh Edition Unix (1979) troff--in other words, before Kernighan's changes for device independence, and it too did not support the "CW" font name.) In Net/2, BSD adopted groff.

This should cover all the bases.

• Any version of groff will do the right thing.
• mandoc will do the right thing because it always claims to be in nroff mode, and it understands the ds, ft, ie, and el requests, and string interpolation escape sequence syntax, well enough to cope.
• AT&T troff, nowadays seen only in Documenter's Workbench (DWB) 3.3 troff (which I think only roff developers like me ever use) and proprietary Unices like Solaris and HP-UX (and sometimes not even those due to adoption of groff, as in Solaris 11) will do the right thing because that troff doesn't define the .g register, (by convention) claiming groff compatibility. The font name "CW" may not work on all AT&T troff output devices, but all of the ones supported by DWB 3.3 troff do support one, and the program issues a diagnostic if a font is unavailable.
• Heirloom Doctools troff will emulate either groff or AT&T troff, as configured by the user.

The only aspect of this solution that I (and, I would guess, mandoc maintainer @ischwarze) don't like is the resort to conditional requests and string definitions, because as a general rule, employment of formatter requests in man pages makes them less portable. But there's really no way around this if one wants portability for this specific problem--the referenced pandoc issue explains why--without giving up the use of monospaced fonts altogether when typesetting man(7) pages, which people are generally not willing to do.

groff man(7)'s macros EX and EE are an alternative--if one is willing to embrace a Ninth Edition Unix (1986) extension--but are not fully suitable if one wants to use a monospaced font in a tbl(1) table, or "inline" amid proportional type. Details available on request.

[g-branden-robinson]

pandoc uses an .ie clause in the header and uses a custom V font, which doesn't play well with mandoc.

pandoc doesn't do this anymore.

[kristapsdz]

If pandoc's going to make a stand on using CR, I'll do the same as a default. However, I'll keep the option available for people to override (e.g., with bold for terminals).

[kristapsdz]

If the new support looks good to you, please close out this issue. Thanks!

[paravoid]

LGTM! @g-branden-robinson may have more thoughts as the expert, but I'll stay optimistic and close the issue.