Re: \- vs - (Was [Re: [PATCH 2/3] system_data_types.7: Add 'clock_t'])

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3576 bytes --]

Hi, Jakub!

At 2020-10-19T20:10:47+0200, Jakub Wilk wrote:
> * Alejandro Colomar <colomar.6.4.3@gmail.com>, 2020-10-19, 19:40:
> > Then, in the following code (taken from printf.3)
> > the escape is wrong (unneeded) by those guidelines?:
> > 
> > [[
> > .SH NAME
> > printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf,
> > vdprintf, vsprintf, vsnprintf \- formatted output conversion
> > ]]
> 
> From the typographical point of view, the most appropriate character
> here would be \(en (en-dash);

I agree with your conclusion below, but I don't believe the above is
correct; there is a long tradition (that I learned from Knuth's TeXbook)
of using en dashes exclusively for numeric ranges[1], though I found a
source[2] that advises its use for non-numeric ranges like airline
route expressions, sports scores, and "complex compound adjectives"[3].
In none of these, however, is the en-dash surrounded by whitespace.

> but for historical reasons, you're supposed to use \- (minus sign).

There's a very _good_ historical reason not to use the en-dash, in that
it was not supported by the AT&T nroff and troff systems used to compose
the earliest Unix manuals[4].  There was no special character escape
documented for it in either the 1976 or 1992 revisions of CSTR #54, the
(Nroff/)Troff User's Manual[5].  You motivated me to do some quick
research; \(en was eventually coined and made its way into Documenter's
Workbench troff, Plan 9 troff, Solaris troff, and Heirloom Doctools
troff, all of which are source descendants of AT&T troff, and of course
GNU troff, which is an independent implementation.  None define it for
all of their output drivers, which makes sense as like any glyph, it's
dependent upon font support.

The Seventh Edition Unix man pages (the first to use the man(7) macro
package), as far as my greps can tell, 100% consistent about using
"<space>\-<space>" to set off the page title(s) from the summary in the
Name section.

mandb(8) implementations are generous in what they accept; the
lexgrog(1) in Colin Watson's man-db package accepts any of:

  --, \(hy, \(mi, \(en, and \(em

...plus the groff forms of the special character escapes (\[xx]), and is
similarly tolerant of whitespace abutting them on either end[6].  Only
a lone hyphen-minus is excepted from the above; I assume that is because
it is too hard to reliably disambiguate from occurrences within page
topic names--like man-pages(7).  However, this generosity is no reason
to over-interpret Postel's Law and advocate chaos.

Given that style authorities are divided over whether em-dashes mandate
or forbid whitespace around them[7], I think it best to regard the
topic/summary separator character as _sui generis_, and \-, which means
nothing in ordinary typography is consequently an excellent choice.

Regards,
Branden

[1] http://visualmatheditor.equatheque.net/doc/texbook.pdf (p. 4, PDF
    page 15)
[2] https://www.grammarly.com/blog/en-dash/
[3] Apparently, one example would be "I prepared an old favorite
    beverage of his, a vanilla ice cream–India pale ale float."
[4] More accurately, the v1 Unix manual (1971) was composed with roff
    ("old roff", as it was subsequently called).  nroff ("new roff") was
    not written until 1972[8].
[5] The title was changed over the course of its lifetime.
[6] https://git.savannah.nongnu.org/cgit/man-db.git/tree/src/lexgrog.l
[7] https://www.thepunctuationguide.com/em-dash.html
[8] https://manpages.bsd.lv/history/mcilroy_21_10_2011.txt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]