Bug#723954: openssl: FTBFS with perl 5.18: pod2man errors

[Daniel Schepler]

Source: openssl
Version: 1.0.1e-3
Severity: serious
X-Debbugs-CC: debian-p...@lists.debian.org
User: debian-p...@lists.debian.org
Usertags: perl-5.18-transition

>From my pbuilder build log:

...
created directory `/tmp/buildd/openssl-1.0.1e/debian/tmp/usr/share/man/man3'
created directory `/tmp/buildd/openssl-1.0.1e/debian/tmp/usr/share/man/man5'
created directory `/tmp/buildd/openssl-1.0.1e/debian/tmp/usr/share/man/man7'
installing man1/CA.pl.1ssl
installing man1/asn1parse.1ssl
installing man1/c_rehash.1ssl
installing man1/ca.1ssl
installing man1/ciphers.1ssl
installing man1/cms.1ssl
cms.pod around line 457: Expected text after =item, not a number
cms.pod around line 461: Expected text after =item, not a number
cms.pod around line 465: Expected text after =item, not a number
cms.pod around line 470: Expected text after =item, not a number
cms.pod around line 474: Expected text after =item, not a number
POD document had syntax errors at /usr/bin/pod2man line 71.
make[1]: *** [install_docs] Error 255
make[1]: Leaving directory `/tmp/buildd/openssl-1.0.1e'
make: *** [install] Error 2
dpkg-buildpackage: error: fakeroot debian/rules binary gave error exit status 2

Although it seems strange for pod2man to reject a list of numbers (as exit
codes with descriptions), which is why I'm CCing debian-perl to see if it's
maybe a bug in pod2man.
-- 
Daniel Schepler


-- 
To UNSUBSCRIBE, email to debian-bugs-rc-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org

Bug#723954: openssl: FTBFS with perl 5.18: pod2man errors

[Russ Allbery]

Daniel Schepler  writes:

> Although it seems strange for pod2man to reject a list of numbers (as
> exit codes with descriptions), which is why I'm CCing debian-perl to see
> if it's maybe a bug in pod2man.

It's actually Pod::Simple that's responsible for this rather than pod2man.
The problem is that POD guesses at the appropriate list type for an =item
list based on the first element, and then if subsequent =item tags appear
to be the wrong type, the output could be wrong.  This mostly affects HTML
output, where there's a significant difference between an ordered list and
a description list and an ordered list has to have the numbers in order.
But Pod::Simple always warns.

Separately, the consensus of the Perl community some time back was that
having tons of documentation out there with POD ERRORS sections was ugly
and was something that we could clean up, so after some discussion the
default in pod2man was changed to fail on formatting errors instead of
silently sticking the errors into the generated POD documentation.

The combination of these two independent changes has caused a lot of
havoc.  :/  But there isn't any consensus that I've seen for reverting
either of them, particularly at this point when I would guess that we're
about 75% of the way through cleaning up the havoc.

The short version is that if you have a description list whose items look
like numbers, you now have to tell POD that they're not supposed to be
numbers for an ordered list and are actually strings.  Two common ways to
do that are to enclose them in C<>, or to add Z<> to the beginning or end
of the number.

I think this makes POD less "plain" and find the change rather unfortunate
but I don't have a lot of control over it at the pod2man level and also
don't have any appetite for having pod2man behave differently than all of
the other POD formatters.

In retrospect, having only one =over command in POD instead of four
(representing simple indentation, ordered, bulleted, and description
lists) was a mistake.

-- 
Russ Allbery (r...@debian.org)   


-- 
To UNSUBSCRIBE, email to debian-bugs-rc-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org

Bug#723954: openssl: FTBFS with perl 5.18: pod2man errors

[peter green]

Tags 723954 +patch
Thanks

I needed this built for raspbian so based on russ's hints I made a patch 
which alters the pod files to make the package build successfully. In 
total 20 pod files were modified (though in one directory I used sed to 
fix the whole directory at once, so it's possible some pod files were 
unnessacerally changed). I have not looked at the resulting manpages.


I also include fixes for incomplete cleanup in the clean target 
discovered while trying to build the source package after fixing the pod 
issues.


Debdiff is attached.
diff -Nru openssl-1.0.1e/debian/changelog openssl-1.0.1e/debian/changelog
--- openssl-1.0.1e/debian/changelog 2013-05-20 15:18:25.0 +
+++ openssl-1.0.1e/debian/changelog 2013-09-26 19:42:48.0 +
@@ -1,3 +1,10 @@
+openssl (1.0.1e-3+rpi1) jessie-staging; urgency=low
+
+  * Fix pod errors (Closes: 723954)
+  * Fix clean target
+
+ -- Peter Michael Green   Thu, 26 Sep 2013 19:29:35 
+
+
 openssl (1.0.1e-3) unstable; urgency=low
 
   * Move  to /usr/include/$(DEB_HOST_MULTIARCH), and
diff -Nru openssl-1.0.1e/debian/patches/fix-pod-errors.patch 
openssl-1.0.1e/debian/patches/fix-pod-errors.patch
--- openssl-1.0.1e/debian/patches/fix-pod-errors.patch  1970-01-01 
00:00:00.0 +
+++ openssl-1.0.1e/debian/patches/fix-pod-errors.patch  2013-09-26 
19:42:35.0 +
@@ -0,0 +1,375 @@
+Description: Fix pod errors
+ The version of pod from perl 5.18 is fussier than previous versions changing
+ thigs that were previously warnings into errors. This patch fixes the errors
+ and makes the package build but I have not checked the correctness of the
+ output.
+Author: Peter Michael Green 
+Bug-Debian: http://bugs.debian.org/723954
+
+--- openssl-1.0.1e.orig/doc/apps/smime.pod
 openssl-1.0.1e/doc/apps/smime.pod
+@@ -308,28 +308,28 @@ remains DER.
+ 
+ =over 4
+ 
+-=item 0
++=item C<0>
+ 
+ the operation was completely successfully.
+ 
+-=item 1 
++=item C<1> 
+ 
+ an error occurred parsing the command options.
+ 
+-=item 2
++=item C<2>
+ 
+ one of the input files could not be read.
+ 
+-=item 3
++=item C<3>
+ 
+ an error occurred creating the PKCS#7 file or when reading the MIME
+ message.
+ 
+-=item 4
++=item C<4>
+ 
+ an error occurred decrypting or verifying the message.
+ 
+-=item 5
++=item C<5>
+ 
+ the message was verified correctly but an error occurred writing out
+ the signers certificates.
+--- openssl-1.0.1e.orig/doc/apps/cms.pod
 openssl-1.0.1e/doc/apps/cms.pod
+@@ -450,28 +450,28 @@ remains DER.
+ 
+ =over 4
+ 
+-=item 0
++=item C<0>
+ 
+ the operation was completely successfully.
+ 
+-=item 1 
++=item C<1> 
+ 
+ an error occurred parsing the command options.
+ 
+-=item 2
++=item C<2>
+ 
+ one of the input files could not be read.
+ 
+-=item 3
++=item C<3>
+ 
+ an error occurred creating the CMS file or when reading the MIME
+ message.
+ 
+-=item 4
++=item C<4>
+ 
+ an error occurred decrypting or verifying the message.
+ 
+-=item 5
++=item C<5>
+ 
+ the message was verified correctly but an error occurred writing out
+ the signers certificates.
+--- openssl-1.0.1e.orig/doc/ssl/SSL_clear.pod
 openssl-1.0.1e/doc/ssl/SSL_clear.pod
+@@ -56,12 +56,12 @@ The following return values can occur:
+ 
+ =over 4
+ 
+-=item 0
++=item C<0>
+ 
+ The SSL_clear() operation could not be performed. Check the error stack to
+ find out the reason.
+ 
+-=item 1
++=item C<1>
+ 
+ The SSL_clear() operation was successful.
+ 
+--- openssl-1.0.1e.orig/doc/ssl/SSL_session_reused.pod
 openssl-1.0.1e/doc/ssl/SSL_session_reused.pod
+@@ -27,11 +27,11 @@ The following return values can occur:
+ 
+ =over 4
+ 
+-=item 0
++=item C<0>
+ 
+ A new session was negotiated.
+ 
+-=item 1
++=item C<1>
+ 
+ A session was reused.
+ 
+--- openssl-1.0.1e.orig/doc/ssl/SSL_set_session.pod
 openssl-1.0.1e/doc/ssl/SSL_set_session.pod
+@@ -37,11 +37,11 @@ The following return values can occur:
+ 
+ =over 4
+ 
+-=item 0
++=item C<0>
+ 
+ The operation failed; check the error stack to find out the reason.
+ 
+-=item 1
++=item C<1>
+ 
+ The operation succeeded.
+ 
+--- openssl-1.0.1e.orig/doc/ssl/SSL_connect.pod
 openssl-1.0.1e/doc/ssl/SSL_connect.pod
+@@ -49,13 +49,13 @@ not clean. It can also occur of action i
+ for non-blocking BIOs. Call SSL_get_error() with the return value B
+ to find out the reason.
+ 
+-=item 0
++=item C<0>
+ 
+ The TLS/SSL handshake was not successful but was shut down controlled and
+ by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+ return value B to find out the reason.
+ 
+-=item 1
++=item C<1>
+ 
+ The TLS/SSL handshake was successfully completed, a TLS/SSL connection has 
been
+ established.
+--- openssl-1.0.1e.orig/doc/ssl/SSL_shutdown.pod
 openssl-1.0.1e/doc/ssl/SSL_shutdown.pod
+@@ -92,7 +92,7 @@ The following return values can occur:
+ 
+ =over 4
+ 
+-=item 1
++=item C<1>
+ 
+ The shutdown was successfully completed. The "close notify" alert was sent
+ and the peer's "close no