Opened 6 years ago

Closed 5 years ago

#512 closed Bug / Defect (fixed)

Man-page contains useless dash escapes

Reported by: Samuli Seppänen Owned by: Samuli Seppänen
Priority: minor Milestone: release 2.3.7
Component: Documentation Version: OpenVPN git master branch (Community Ed)
Severity: Not set (select this one, unless your'e a OpenVPN developer) Keywords:
Cc: David Sommerseth, JJK

Description

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.

Change History (15)

comment:1 Changed 6 years ago by Samuli Seppänen

Version: 2.2.2git master branch

comment:2 Changed 5 years ago by Gert Döring

...so?

comment:3 Changed 5 years ago by Samuli Seppänen

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

comment:4 Changed 5 years ago by Samuli Seppänen

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

comment:5 Changed 5 years ago by Samuli Seppänen

Milestone: release 2.3.7

comment:6 Changed 5 years ago by Samuli Seppänen

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

comment:7 Changed 5 years ago by Samuli Seppänen

Discussion of the patch goes on on the mailinglist.

comment:8 Changed 5 years ago by Gert Döring

Cc: David Sommerseth JJK added

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

comment:9 Changed 5 years ago by 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:

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

comment:10 Changed 5 years ago by Samuli Seppänen

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

comment:11 Changed 5 years ago by Samuli Seppänen

Owner: set to Samuli Seppänen
Status: newassigned

comment:12 Changed 5 years ago by Samuli Seppänen

Status: assignedaccepted

comment:13 Changed 5 years ago by 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.

comment:14 Changed 5 years ago by Samuli Seppänen

Mentioned this issue on the developer documentation page.

comment:15 Changed 5 years ago by Samuli Seppänen

Resolution: fixed
Status: acceptedclosed

Fixed in Git "master" also. Closing.

Note: See TracTickets for help on using tickets.