Bug#785353: manpages, hyphens, minus signs, HTML, and lintian

[Josh Triplett <josh@joshtriplett.org>]

[Copying debian-devel and groff@packages.debian.org for a broader
audience, to get more thoughts on this.  Also, please CC me on replies.]

In bug 785353, lintian dropped the venerable hyphen-used-as-minus-sign
check, citing the volume of issues, the relatively minor importance, and
this:

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.  That
doesn't look correct in running text, such as in an --option-name or a
command-name.

For an example of this, try "man -H man"; look at the minus signs in
"--help" or "-a", and compare to the correct-looking dashes in "man-db"
(third paragraph of the OVERVIEW section).

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 "-".

I don't know if this deserves some kind of lintian check, but it does
seem like a (very minor) bug in various manpages.

- Josh Triplett