Silence "warning: cannot select font 'C'" with GNU roff 1.23

[debarshiray]

• closes new groff incompatibilities? #99

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 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. Hence, 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.

So, just don't attempt to use monospace for inline code enclosed in single backticks and stick to bold everywhere.

As suggested by G. Branden Robinson.

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

#99
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1049968

[thaJeztah]

Therefore, the use of \fC is only relevant for non-terminal outputs, like HTML and PS

Thanks for the extra explanation; yes, I don't think code in this repo is used for that, but /cc @cpuguy83 if you're aware if this would affect anything.

If it's indeed not used, then this seems like an appropriate fix

[debarshiray]

Therefore, the use of \fC is only relevant for non-terminal outputs, like HTML and PS

Thanks for the extra explanation; yes, I don't think code in this repo is used for that, but /cc @cpuguy83 if you're aware if this would affect anything.

If it's indeed not used, then this seems like an appropriate fix

One can take a man page generated by go-md2man(1) and convert it to HTML or PS with:

$ man -Thtml <man-page>  > foo.html
$ man -Tps <man-page>  > foo.ps

See this Debian bug for the detailed discussion:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1049968

[debarshiray]

Therefore, the use of \fC is only relevant for non-terminal outputs, like HTML and PS

Thanks for the extra explanation; yes, I don't think code in this repo is used for that, but /cc @cpuguy83 if you're aware if this would affect anything.
If it's indeed not used, then this seems like an appropriate fix

One can take a man page generated by go-md2man(1) and convert it to HTML or PS with:

I updated the commit message to make it clear.

[cpuguy83]

With using man to convert to html I see no visible difference between the output of current HEAD and this PR, so this seems fine.
Not to mention the intention of the the tool is to create documents for man to read and not HTML.
Presumably most people would create the HTML from the original markdown.

LGTM

[cpuguy83]

Also thanks for all the detailed messages here and downstream.
For a project I threw together in a weekend to satisfy a particular need that randomly got wide adoption these sorts of changes can be difficult to review without extensive research, which you've already done for me. 🙇 ❤️

[cpuguy83]

I published v2.0.3 with this patch (and a few others).

[debarshiray]

Wow, thanks for the release @cpuguy83 !

For a project I threw together in a weekend to satisfy a particular need that randomly got wide adoption these sorts of changes can be difficult to review without extensive research, which you've already done for me. 🙇 ❤️

I can understand. I have been subject to that experience too. :)

[debarshiray]

With using man to convert to html I see no visible difference between the output of current HEAD and this PR,

You might see a difference if you have inline code enclosed in single backticks in the Markdown. It would change from being monospace to being bold in the HTML and PS renders.

so this seems fine. Not to mention the intention of the the tool is to create documents for man to read and not HTML. Presumably most people would create the HTML from the original markdown.

Yes, totally agree about this part.