Man-page contains useless dash escapes

[Samuli Seppänen]

The dashes for the man-page have been partially escaped, for example like this:

\-\-win\-sys

The partial escaping originates from commit 886593ac4ae ("The man page needs dash escaping in UTF-8 environments") from 2010, which fixes a bug from 2005.

It looks like that back then, in 2005-2010 one could not search for, say, --win-sys on the man-page on a UTF-8-enabled system, unless the dashes were escaped (\-\-win\-sys).

I tried to reproduce the problem on Debian 6, CentOS 6 and Ubuntu 14.04 and failed, at least when using "less" as the pager. Anecdotal evidence tells us that the actual problem, which was in groff(?), was solved, and the "escape dashes" workaround in OpenVPN (and other projects) remained. More details are available in the openvpn-devel ​mailing list thread.

Our current problem now is that dash escaping on the man-page is inconsistent. Removing the dashes does not seem to break anything, so that's what we should probably do.

[Gert Döring]

...so?

[Samuli Seppänen]

I can scrap the dashes and provide a patch if I get an ACK for it.

[Samuli Seppänen]

I got an ACK for this from cron2. I'll provide separate patches for 2.3.x and Git master.

[Samuli Seppänen]

Sent patches for "master" and "release/2.3" to openvpn-devel.

[Samuli Seppänen]

Discussion of the patch goes on ​on the mailinglist.

[Gert Döring]

So, I went looking... this is where it came from:

commit 48fe8bb37167b57722d209274626f5f91975c001
Author: Jan Brinkmann <the-luckyduck@…>
Date: Sun Feb 28 23:29:29 2010 +0100

The man page needs dash escaping in UTF-8 environments

There was a debian bugreport which was filed in 2005 . It was patched but
it seems that nobody forwarded the patch to the openvpn project itself.

...

Signed-off-by: David Sommerseth <dazo@…>
Tested-by: Jan Just Keijser <janjust@…>
Tested-by: Pavel Shramov <shramov@…>
Tested-by: Samuli Seppänen <samuli@…>

Maybe it's truly no longer relvant, maybe not. I don't know, but we should be consistent, one way or the other...

[Samuli Seppänen]

From "man 7 groff_char":

the ISO latin1 `Hyphen, Minus Sign' (code 45) prints as a hyphen;
a minus sign can be obtained with `\-'.

Here's a good explanation of the problems hyphens could cause:

• ​https://lintian.debian.org/tags/hyphen-used-as-minus-sign.html

As can be seen from the page above, tons and tons of packages in Debian lack proper escaping. I can verify this on Ubuntu 14.04:

$ find /usr/share/man/man1 -name "*.gz" -exec zgrep -E "\-\-" {} +
< tons of output >
$ find /usr/share/man/man1 -name "*.gz" -exec zgrep -E "\\\-\\\-" {} +
< tons of output >

There are also lots of examples of partial and mixed escaping.

As we were ​unable to reproduce the "searching the man-page fails" issue on any real systems with an unpatched openvpn.8 man-page, I suspect some component in the display chain converts the hyphens into minus signs, even if they are unescaped. This hypothesis is supported by this statement (​source):

An unfortunate bit of arcane syntax is that dashes in options should
be prefixed by backslashes. Thus, write \-\-bits, not just --bits.
The Debian and Ubuntu implementation of man treats them the same,
for terminal output, but this is not portable. Technically a naked
 - means a hyphen, whereas \- means a minus sign. Typographically
these are distinct, and they are also distinct in Unicode. The
typesetter is free to break a line at a hyphen, but not at a minus.
For dashes in options, you should thus use minuses, but in normal text,
for normal words, the hyphen.

Based on this information I believe the correct approach is to escape dashes in options, but not anywhere else.

I will provide a new patch if I get a pre-ACK from someone (including mandree).

[Samuli Seppänen]

Cron2 gave a pre-ACK for the new approach. Please complain soon if you think the new approach is wrong.

[Samuli Seppänen]

The patch for release/2.3 branch has been merged. A patch for Git "master" was sent to the list, but has not yet been ACKed.

[Samuli Seppänen]

Mentioned this issue on the developer documentation page.

[Samuli Seppänen]

Fixed in Git "master" also. Closing.