Skip to content

Commit

Permalink
Silence "warning: cannot select font 'C'" with GNU roff 1.23
Browse files Browse the repository at this point in the history
It's difficult to portably ask the man(7) macro package for a monospaced
font (whether it's referred to as C, CW or CR) without any extra
configuration.  That's what leads to:
  warning: cannot select font 'C'

This can be reproduced on Fedora 39, which has GNU roff 1.23, with:
  $ man crun >/dev/null
  troff:<standard input>:25: warning: cannot select font 'C'
  troff:<standard input>:134: warning: cannot select font 'C'
  ...
  $ man podman >/dev/null
  troff:<standard input>:15: warning: cannot select font 'C'
  troff:<standard input>:25: warning: cannot select font 'C'
  ...
  $ man toolbox >/dev/null
  troff:<standard input>:33: warning: cannot select font 'C'
  troff:<standard input>:43: warning: cannot select font 'C'
  ...

These may look like odd uses of man(1), but it's used by the Toolbx [1]
test suite to ensure that 'toolbox help' and 'toolbox --help' do render
the toolbox(1) manual, which, like crun(1) and podman(1), is generated
by go-md2man(1).

The warnings come from the current \\fB\\fC sequence for inline code
enclosed in single backticks (ie., `) that uses 'C' to ask for a
monospace font.  Other than the difficulties with portably asking the
man(7) macro package for a monospace font, the \\fB\\fC sequence has
some oddities.

If a monospace font does get selected by \\fC, then the request for bold
with \\fB gets masked, with the possible surprise that switching back to
the 'previous font' with \\fP will result in bold.  This is what happens
when the manual is rendered in HyperText Markup Language or PostScript:
  $ man --troff-device html <manual> > foo.html
  $ man --troff-device ps <manual> > foo.ps

If the manual is displayed on a terminal device, \\fC is a NOP because
terminals are always monospaced and can't change the font family.  So,
only \\fB is in effect.

Therefore, the use of \\fC is only relevant for non-terminal outputs,
like HTML and PS.  Since HTML and PS use serif fonts by default, an
inline switch to monospace looks visually jarring.  This is different
from other common uses of monospace for inline code, such as on GitLab
and GitHub, where sans-serif fonts are used by default.

Hence, just don't attempt to use monospace for inline code enclosed in
single backticks (ie., `) and stick to bold everywhere.

As suggested by G. Branden Robinson.

[1] https://containertoolbx.org/
    https://github.com/containers/toolbox

cpuguy83#99
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1049968
  • Loading branch information
debarshiray committed Oct 10, 2023
1 parent e8098c3 commit d85280d
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 13 deletions.
2 changes: 1 addition & 1 deletion md2man/roff.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ const (
hruleTag = "\n.ti 0\n\\l'\\n(.lu'\n"
linkTag = "\n\\[la]"
linkCloseTag = "\\[ra]"
codespanTag = "\\fB\\fC"
codespanTag = "\\fB"
codespanCloseTag = "\\fR"
codeTag = "\n.EX\n"
codeCloseTag = "\n.EE\n"
Expand Down
24 changes: 12 additions & 12 deletions md2man/roff_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -128,10 +128,10 @@ func TestStrong(t *testing.T) {
".nh\n\n.PP\nmix of **markers__\n",

"**`/usr`** : this folder is named `usr`\n",
".nh\n\n.PP\n\\fB\\fB\\fC/usr\\fR\\fP : this folder is named \\fB\\fCusr\\fR\n",
".nh\n\n.PP\n\\fB\\fB/usr\\fR\\fP : this folder is named \\fBusr\\fR\n",

"**`/usr`** :\n\n this folder is named `usr`\n",
".nh\n\n.PP\n\\fB\\fB\\fC/usr\\fR\\fP :\n\n.PP\nthis folder is named \\fB\\fCusr\\fR\n",
".nh\n\n.PP\n\\fB\\fB/usr\\fR\\fP :\n\n.PP\nthis folder is named \\fBusr\\fR\n",
}
doTestsInline(t, tests)
}
Expand Down Expand Up @@ -168,13 +168,13 @@ func TestEmphasisMix(t *testing.T) {
func TestCodeSpan(t *testing.T) {
tests := []string{
"`source code`\n",
".nh\n\n.PP\n\\fB\\fCsource code\\fR\n",
".nh\n\n.PP\n\\fBsource code\\fR\n",

"` source code with spaces `\n",
".nh\n\n.PP\n\\fB\\fCsource code with spaces\\fR\n",
".nh\n\n.PP\n\\fBsource code with spaces\\fR\n",

"` source code with spaces `not here\n",
".nh\n\n.PP\n\\fB\\fCsource code with spaces\\fRnot here\n",
".nh\n\n.PP\n\\fBsource code with spaces\\fRnot here\n",

"a `single marker\n",
".nh\n\n.PP\na `single marker\n",
Expand All @@ -186,19 +186,19 @@ func TestCodeSpan(t *testing.T) {
".nh\n\n.PP\nmarkers with a space\n",

"`source code` and a `stray\n",
".nh\n\n.PP\n\\fB\\fCsource code\\fR and a `stray\n",
".nh\n\n.PP\n\\fBsource code\\fR and a `stray\n",

"`source *with* _awkward characters_ in it`\n",
".nh\n\n.PP\n\\fB\\fCsource *with* _awkward characters_ in it\\fR\n",
".nh\n\n.PP\n\\fBsource *with* _awkward characters_ in it\\fR\n",

"`split over\ntwo lines`\n",
".nh\n\n.PP\n\\fB\\fCsplit over\ntwo lines\\fR\n",
".nh\n\n.PP\n\\fBsplit over\ntwo lines\\fR\n",

"```multiple ticks``` for the marker\n",
".nh\n\n.PP\n\\fB\\fCmultiple ticks\\fR for the marker\n",
".nh\n\n.PP\n\\fBmultiple ticks\\fR for the marker\n",

"```multiple ticks `with` ticks inside```\n",
".nh\n\n.PP\n\\fB\\fCmultiple ticks `with` ticks inside\\fR\n",
".nh\n\n.PP\n\\fBmultiple ticks `with` ticks inside\\fR\n",
}
doTestsInline(t, tests)
}
Expand Down Expand Up @@ -331,9 +331,9 @@ row one This is a short line.
row|two Col1 should not wrap.
row three no|wrap
row four Inline \fIcursive\fP should not wrap.
row five Inline \fB\fCcode markup\fR should not wrap.
row five Inline \fBcode markup\fR should not wrap.
row six T{
A line that's longer than 30 characters with inline \fB\fCcode markup\fR or \fIcursive\fP should not wrap.
A line that's longer than 30 characters with inline \fBcode markup\fR or \fIcursive\fP should not wrap.
T}
row seven T{
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent eu ipsum eget tortor aliquam accumsan. Quisque ac turpis convallis, sagittis urna ac, tempor est. Mauris nibh arcu, hendrerit id eros sed, sodales lacinia ex. Suspendisse sed condimentum urna, vitae mattis lectus. Mauris imperdiet magna vel purus pretium, id interdum libero.
Expand Down

0 comments on commit d85280d

Please sign in to comment.