Daniel Schepler <dschep...@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 (r...@debian.org) <http://www.eyrie.org/~eagle/> -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
