[squid-dev] [PATCH] fix escaping errors in manual pages causing information loss

[Ingo Schwarze]

Hi,

while auditing manual pages in the OpenBSD ports tree, i noticed
serious escaping errors in four of the squid manuals that cause
information loss, in most cases loss of important information in
the SYNOPSIS.

The following patch against bazaar trunk fixes those issues.

Stuart Henderson, who is maintaining the OpenBSD port of squid,
advised that sending the patch to this list would be appropriate.


The reasons why the escaping is wrong are:

 1) In the roff language, \" introduces a comment,
    hence the rest of the input line is discarded by
    all formatters.

 2) In the roff language, \\ does *not* produce a printable
    backslash but merely delays expansion of the escape sequence
    (which is practically never what you want, unless you are
    programming a new macro package).  Consequently, "\\n'" ends
    up being interpreted as an access to the number register with
    the name "'" (yes, roff does allow identifiers consisting of
    special characters in some contexts), which doesn't exist and
    hence yields the output string "0".

Thanks for developing squid!

Yours,
  Ingo

P.S.
I'm not attempting to fix all manual page syntax errors that cause
misformatting (that would cause a very serious amount of work), but
only those that cause information loss.

-- 
Ingo Schwarze <schwarze at usta.de>
http://www.openbsd.org/   <schwarze at openbsd.org>
http://mdocml.bsd.lv/     <schwarze at mdocml.bsd.lv>


=== modified file 'src/acl/external/file_userip/ext_file_userip_acl.8'
--- src/acl/external/file_userip/ext_file_userip_acl.8	2017-01-01 00:14:42 +0000
+++ src/acl/external/file_userip/ext_file_userip_acl.8	2017-05-11 16:49:06 +0000
@@ -68,7 +68,7 @@
 .B ALL 
 and 
 .B NONE 
-, which mean \"any user on this IP address may authenticate\" or \"no user on this IP address may authenticate\".
+, which mean \(dqany user on this IP address may authenticate\(dq or \(dqno user on this IP address may authenticate\(dq.
 .
 .SH AUTHOR
 This program was written by

=== modified file 'src/auth/basic/LDAP/basic_ldap_auth.8'
--- src/auth/basic/LDAP/basic_ldap_auth.8	2017-03-31 08:57:46 +0000
+++ src/auth/basic/LDAP/basic_ldap_auth.8	2017-05-11 16:44:30 +0000
@@ -5,9 +5,9 @@
 .
 .SH SYNOPSIS
 .if !'po4a'hide' .B basic_ldap_auth
-.if !'po4a'hide' .B \-b\ \"
+.if !'po4a'hide' .B \-b\ \(dq
 base DN
-.if !'po4a'hide' .B \"\ [\-u
+.if !'po4a'hide' .B \(dq\ [\-u
 attribute
 .if !'po4a'hide' .B ]\ [
 options
@@ -20,11 +20,11 @@
 .if !'po4a'hide' .B ]...
 .br
 .if !'po4a'hide' .B basic_ldap_auth
-.if !'po4a'hide' .B \-b\ \"
+.if !'po4a'hide' .B \-b\ \(dq
 base DN
-.if !'po4a'hide' .B \"\ \-f\ \"
+.if !'po4a'hide' .B \(dq\ \-f\ \(dq
 LDAP search filter
-.if !'po4a'hide' .B \"\ [
+.if !'po4a'hide' .B \(dq\ [
 options
 .if !'po4a'hide' .B ]\ [
 LDAP server name
@@ -74,7 +74,7 @@
 The search filter can contain up to 15 occurrences of
 .B %s
 which will be replaced by the username, as in
-.B "\"uid\=%s\""
+.B "\(dquid\=%s\(dq"
 for RFC2037 directories. For a detailed description of LDAP search
 filter syntax see RFC2254.
 .br

=== modified file 'src/auth/basic/RADIUS/basic_radius_auth.8'
--- src/auth/basic/RADIUS/basic_radius_auth.8	2017-01-01 00:14:42 +0000
+++ src/auth/basic/RADIUS/basic_radius_auth.8	2017-05-11 16:47:05 +0000
@@ -9,9 +9,9 @@
 config file
 .br
 .if !'po4a'hide' .B basic_radius_auth
-.if !'po4a'hide' .B "\-h \""
+.if !'po4a'hide' .B "\-h \(dq"
 server name
-.if !'po4a'hide' .B "\" [\-p "
+.if !'po4a'hide' .B "\(dq [\-p "
 port
 .if !'po4a'hide' .B "] [\-i "
 identifier

=== modified file 'tools/squidclient/squidclient.1'
--- tools/squidclient/squidclient.1	2017-01-01 00:14:42 +0000
+++ tools/squidclient/squidclient.1	2017-05-11 16:51:31 +0000
@@ -86,7 +86,7 @@
 .if !'po4a'hide' .TP
 .if !'po4a'hide' .B "\-H 'string'"
 Extra headers to send. Use
-.B '\\n'
+.B '\en'
 for new lines.
 .
 .if !'po4a'hide' .TP