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

[Kinkie]

Hi Ingo,
  I've merged your changes as Squid-5 revno 15135.
Thanks for your contribution!

On Thu, May 11, 2017 at 6:22 PM, Ingo Schwarze <schwarze at usta.de> wrote:
> 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
>
> _______________________________________________
> squid-dev mailing list
> squid-dev at lists.squid-cache.org
> http://lists.squid-cache.org/listinfo/squid-dev



-- 
    Francesco