Re: manpages, hyphens, minus signs, HTML, and lintian

[Colin Watson <cjwatson@debian.org>]

On Fri, Jul 01, 2016 at 10:57:45PM -0700, Josh Triplett wrote:
> On Fri, 15 May 2015 22:15:14 +0200 Jakub Wilk <jwilk@debian.org> wrote:
> > Yeah, these days even upstream groff renders both - and \- as
> > HYPHEN-MINUS.
> 
> However, this doesn't appear true with current groff when rendering to
> HTML.  "man -H" (or "man -Thtml") passes "-" through as "-", but renders
> "\-" as "&minus;", which browsers typically render as U+2122.

I think that's simply a bug in groff and should be reported as such.
(To fix it, we could for example adjust \- specifically when rendering
man/mdoc output to HTML.)

> As far as I can tell, manpages should never use "\-" at all unless they
> actually want a mathematical minus sign (or in the one line in the NAME
> section between the program name and description, as whatis and apropos
> apparently require that).  (For manpages that want an em-dash, use the
> four-character sequence "\(em".)
> 
> Any time a manpage wants "the dash corresponding to the key '-' on the
> keyboard", which includes any text the user would type on the keyboard
> using that key such as an --option or command-name, the manpage should
> just use "-".

That's specifically contrary to upstream's consistent typographical
advice over the years, and your suggested advice has its own problems
such as inappropriate line-breaks due to hyphenation.  I don't mind that
we've dropped the lintian check nowadays, but please don't reverse it.

-- 
Colin Watson                                       [cjwatson@debian.org]