[Pkg-openssl-devel] Bug#723954: openssl: FTBFS with perl 5.18: pod2man errors

[Russ Allbery]

Daniel Schepler <dschepler at gmail.com> 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 (rra at debian.org)               <http://www.eyrie.org/~eagle/>