Add more dash escaping to the man page
PATCH 1/1 Add more dash escaping to the man page
From: Alberto Gonzalez Iniesta <[email protected]...>
This patch continues the work started in commit 886593ac4ae ("The man page needs dash escaping in UTF-8 environments"). This patch is one of the patches included in Debian's OpenVPN packages.
--- doc/openvpn.8 | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-)
doc/openvpn.8 +14 -14
@@ -21,13 +21,13 @@ .\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA .\" .\" Manual page for openvpn -.\ +.\" .\" SH section heading .\" SS subsection heading .\" LP paragraph .\" IP indented paragraph .\" TP hanging label -.\ +.\" .\" .nf -- no formatting .\" .fi -- resume formatting .\" .ft 3 -- boldface
@@ -2611,7 +2611,7 @@ command. .B \-\-management-signal Send SIGUSR1 signal to OpenVPN if management session disconnects. This is useful when you wish to disconnect an OpenVPN session on -user logoff. For --management-client this option is not needed since +user logoff. For \-\-management-client this option is not needed since a disconnect will always generate a SIGTERM. .\"********************************************************* .TP
@@ -3990,7 +3990,7 @@ is 15 seconds. This option is only relevant in UDP mode, i.e. when either .B \-\-proto udp -is specifed, or no +is specified, or no .B \-\-proto option is specified.
@@ -5173,7 +5173,7 @@ not specified, OpenVPN will use the SystemRoot environment variable. This option have changed behaviour in OpenVPN 2.3. Earlier you had to define -.B --win-sys env +.B \-\-win-sys env to use the SystemRoot environment variable, otherwise it defaulted to C:\\WINDOWS. It is not needed to use the .B env
@@ -5216,7 +5216,7 @@ virtual DHCP server address. In .B \-\-dev tun mode, OpenVPN will cause the DHCP server to masquerade as if it were coming from the remote endpoint. The optional offset parameter is -an integer which is > -256 and < 256 and which defaults to 0. +an integer which is > \-256 and < 256 and which defaults to 0. If offset is positive, the DHCP server will masquerade as the IP address at network address + offset. If offset is negative, the DHCP server will masquerade as the IP
@@ -5550,20 +5550,20 @@ and increments by +1 for every new client (linear mode). The setting controls the size of the pool. Due to implementation details, the pool size must be between /64 and /112. .TP -.B --ifconfig-ipv6-push ipv6addr/bits ipv6remote +.B \-\-ifconfig-ipv6-push ipv6addr/bits ipv6remote for ccd/ per-client static IPv6 interface configuration, see -.B --client-config-dir +.B \-\-client-config-dir and -.B --ifconfig-push +.B \-\-ifconfig-push for more details. .TP -.B --iroute-ipv6 ipv6addr/bits +.B \-\-iroute-ipv6 ipv6addr/bits for ccd/ per-client static IPv6 route configuration, see -.B --iroute +.B \-\-iroute for more details how to setup and use this, and how -.B --iroute +.B \-\-iroute and -.B --route +.B \-\-route interact. .\"*********************************************************
@@ -6049,7 +6049,7 @@ or configuration file. .TP .B peer_cert Temporary file name containing the client certificate upon -connection. Useful in conjunction with --tls-verify +connection. Useful in conjunction with \-\-tls-verify .\"********************************************************* .TP .B script_context
Signature · 1 line
1.9.1
Quoted 5 lines · On Mon, 2015-01-26 at 10:38 +0200, [email protected]... wrote:
From: Alberto Gonzalez Iniesta <[email protected]...>
This patch continues the work started in commit
886593ac4ae("The man page needs dash escaping in UTF-8 environments"). This patch is one of the patches included in Debian's OpenVPN packages.
Note that this isn't perfect either. The escaped \- is supposedly rendered as a minus sign... but you don't actually *want* a minus sign.
If you ever render the manual into HTML, that's exactly what you'll
get: U+2212 MINUS SIGN. I've had users complaining to me because when they cut and paste from an HTML-rendered man page, their command lines don't work.
What you really want is U+002D HYPHEN-MINUS¹. I think it could actually be considered a groff bug if you *do* get U+002D HYPHEN-MINUS in the UTF-8 terminal output — it should be U+2212 MINUS SIGN there too, according to the definition.
FWIW I *can* search for 'For --management-client' even before this patch, on Fedora 21. Changing to \- isn't required to fix the searching here. Is it still required on Debian?
Signature · 1 line
dwmw2
Quoted 15 lines · On Mon, 2015-01-26 at 10:38 +0200, [email protected]... wrote:
Quoted 5 lines
From: Alberto Gonzalez Iniesta <[email protected]...>
This patch continues the work started in commit
886593ac4ae("The man page needs dash escaping in UTF-8 environments"). This patch is one of the patches included in Debian's OpenVPN packages.Note that this isn't perfect either. The escaped \- is supposedly rendered as a minus sign... but you don't actually *want* a minus sign.
If you ever render the manual into HTML, that's exactly what you'll
get: U+2212 MINUS SIGN. I've had users complaining to me because when they cut and paste from an HTML-rendered man page, their command lines don't work.
Quoted 9 lines
What you really want is U+002D HYPHEN-MINUS¹. I think it could actually be considered a groff bug if you *do* get U+002D HYPHEN-MINUS in the UTF-8 terminal output — it should be U+2212 MINUS SIGN there too, according to the definition.
FWIW I *can* search for 'For --management-client' even before this patch, on Fedora 21. Changing to \- isn't required to fix the searching here. Is it still required on Debian?
Hi,
The original problem seemed to be that strings like "--win-sys" could not be found from the man-page unless the dashes were escaped:
<https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=296133>
I tried to reproduce the problem on Ubuntu 14.04, Debian 6 and CentOS 6 and was unable to. Having or not having escaped dashes made absolutely no difference. Note that I only tested "less" as the pager. In any case, it looks like the problem got fixed outside of OpenVPN, which leaves us with an inconsistent escaping style on the man-page.
Signature · 5 lines
Samuli Seppänen Community Manager OpenVPN Technologies, Inc irc freenode net: mattock
Hi,
Quoted 5 lines · Samuli Seppänen
I tried to reproduce the problem on Ubuntu 14.04, Debian 6 and CentOS 6 and was unable to. Having or not having escaped dashes made absolutely no difference. Note that I only tested "less" as the pager. In any case, it looks like the problem got fixed outside of OpenVPN, which leaves us with an inconsistent escaping style on the man-page.
In that case, I'd actually prefer to have everything *un*escaped, as it makes handling of the manpage slightly easier.
If that does the right thing, that is :-)
gert
Signature · 4 lines
USENET is *not* the non-clickable part of WWW!
//www.muc.de/~gert/
Gert Doering - Munich, Germany [email protected]...
fax: +49-89-35655025 [email protected]...Am 26.01.2015 um 14:04 schrieb David Woodhouse:
Quoted 3 lines
FWIW I *can* search for 'For --management-client' even before this patch, on Fedora 21. Changing to \- isn't required to fix the searching here. Is it still required on Debian?
I have a rather faint recollection because I tried fixing this in one of my projects, possibly fetchmail, and figured that some distros, once upon a time, had hacked some of their roff files in an effort to cater for broken man pages and render things more beautifully... chances are you get different results on older distros.