The groff_man (7)` man page indicates that `-` characters will be
treated as typographic hyphens and are not appropriate for cases
where the output should be copy-pasteable as an ASCII
hyphen-minus character. (E.g. in command line options.)
However, until a recent update groff man did not actually do this;
it treated `-` and `\-` the same. With the new update (1.23.0)
the two are distinguished (see https://lwn.net/Articles/947941/
for background), so now it is important that pandoc escape `-`.
This reverts ee60ba5252.
That change was motivated by a problem with backslash-escaping
`-` in a filename for .PSPIC. That's simply a separate issue;
we shouldn't do the normal escapes in such a context. It has
been addressed in the previous commit.
The aim here (see #9020) is to produce more standard and more
portable man pages. To that end:
- We revert the fanciness introduced in #7506, which employs a
custom font name V and a macro that makes this act like boldface
in a terminal and monospace in other formats. Unfortunately,
this code uses a mechanism that is not portable (and does not
work in mandoc).
- Instead of using V for inline code, we simply use CR.
Note that `\f[CR]` is emitted instead of plain `\f[C]`,
because there is no C font in man. (This produces warnings
in recent versions of groff.)
- For code blocks, we now use the `.EX` and `.EE` macros,
together with `.IP` for spacing and indentation. This gives
more standard code that can be better interpreted e.g. by mandoc.
The V font is defined conditionally, so that it renders
like CB in output formats that support that, and like B
in those that don't (e.g. the terminal).
We could just redefine C, but this would affect code
blocks, too, and putting them all in boldface looks ugly,
I think.
Possible drawback: fragments created by pandoc's man
writer will presuppose a nonstandard V font.
Closes#7506.
Supersedes 253467a549.
Closes#7506.
This also allows us to get rid of some special casing
on definition lists that ensured that options in code
spans would be boldface. (If this change is ever reverted,
we'll need that again.)
Now we boldface code but not other things. This matches the
most common style in man pages (particularly option lists).
Also, remove a regression in the last commit in which 'nowrap'
was removed.
John MacFarlane