Hi folks, I've decided to put `QS` and `QE` macros for man(7) on the shelf-- indefinitely and perhaps permanently.
Instead I'm adding some advice to the groff_man_style(7) page in the
"Notes" section alongside other Q&As.
• When and how should I use quotation marks?
As noted above in subsection “Font style macros”, apply quotation
marks to “brief specimens of literal text, such as article
titles, inline examples, mentions of individual characters or
short strings, and (sub)section headings in man pages”. When
setting examples of multi‐word literals, such as Unix commands,
inline (as opposed to displaying them between .EX and .EE), use
of quotation marks is important to ensure that the boundaries of
the quotation are clear even when the material is stripped of
font styling by, for example, copy‐and‐paste operations. groff,
Heirloom Doctools troff, neatroff, and mandoc support all of the
special characters \(oq, \(cq, \(lq, \(rq, \(aq, and \(dq
described in section “Portability” above. Solaris 10, DWB, and
Plan 9 troffs do not.
Historically, man pages used ` and ' exclusively for directional
single quotation marks. However, in recent years, some
distributors of groff have chosen to override the meanings of
these characters in man pages, remapping them to their Unicode
Basic Latin code points. Unfortunately, ` and ' are the only
reliable means of obtaining directional single quotation marks in
AT&T troff; in that implementation, often no special character
escape sequences exist to obtain them. Further, in AT&T troff,
the glyph repetoire, like the set of supported font names, is
device‐specific. To achieve quotation portably in man pages
rendered both by AT&T and more modern troffs, consider adding a
preamble to your page after the .TH call as follows.
.ie \n(.g \{\
. ds oq \(oq
. ds cq \(cq
.\}
.el \{\
. ds oq `
. ds cq '
.\}
You must then use the \* escape sequence to interpolate the
quotation mark strings.
The command
.RB \*(oq "while ! git pull; do sleep 10; done" \*(cq
retries an update from our repository until it succeeds.
If this procedure seems complex, petition your distributor to
revert their remapping of the ` and ' characters.
The foregoing will probably be in my next push.
Regards,
Branden
signature.asc
Description: PGP signature
