Skip to content

doc: fix display of "problematic" ASCII characters

Rodrigo Muino Tomonari requested to merge github/fork/Cutlery-Drawer/man-punct into main

When preparing output for a terminal that supports Unicode, Groff remaps the following characters to typographically "fancier" versions:

^ (U+005E)  ->  ˆ (U+02C6)
~ (U+007E)  ->  ˜ (U+02DC)
- (U+002D)  ->  ‐ (U+2010)
` (U+0060)  ->  ‘ (U+2018)
' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output (i.e., PDF and PostScript), but frequently problematic in terminal display. As described in groff_char(7), the following escape sequences are needed to display the aforementioned characters as they appear in source code:

^   ->   \(ha   (Mnemonic: "hat")
~   ->   \(ti   (Mnemonic: "tilde")
-   ->   \-
`   ->   \(ga   (Mnemonic: "grave accent")
'   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source code, and are completely opaque to the majority of man page authors (who only care about terminal display). A simpler solution is to use Roff's .tr to translate these characters automatically.

Merge request reports