| Subject: | Support for "pod2man --utf8" |
Hi,
I'm a maintainer of the Debian Perl core package, and we'd like to have
better UTF-8 support in Pod::Perldoc::ToMan for our upcoming Debian
stable release ("lenny").
It would be nice if Pod::Perldoc::ToMan could optionally (preferably
with the default being a build-time configuration option) add the
'--utf8' option to the pod2man invocation if Pod::Man is new enough.
As discussed in http://bugs.debian.org/480997, UTF-8 support in Pod::Man
has been improved recently. From podlators-2.1.0 onwards, there's now a
'--utf8' switch for pod2man, which makes the script output literal UTF-8
characters. Without the switch, all non-ASCII characters are converted
either to a *roff escape sequence that tries to create a properly
accented character (at least for troff output) or to "X".
For some further confusion, even older Pod::Man versions (before
podlators-2.00, including those shipped with Perl 5.8.8) just passed
non-ASCII characters through as-is. This was undefined behaviour, but it
turned out people were more or less relying on it.
According to Russ Allbery, the podlators author, the '--utf8' option
can't be made the default because it breaks some nroff implementations.
I'm contemplating on adding the attached patch for the Debian Perl
package. I'd love to hear your thoughts on this. I think we can use
'--utf8' unconditionally because our nroff can handle it, so I haven't
looked at that part.
As a small implementation detail, pod2man doesn't (currently) support
anything like '--utf8=1', so I didn't use the 'turn the switches into
CLIs' part in ToMan.pm for this.
For reference, this is Debian bug #492037,
<http://bugs.debian.org/492037>.
Thanks for your work on Perl,
--
Niko Tyni
ntyni@debian.org
| Subject: | 492037.patch |
Make /usr/bin/perldoc invoke pod2man with the "--utf8" option if it detects a new enough Pod::Man version. (Closes: #492037)
diff --git a/lib/Pod/Perldoc/ToMan.pm b/lib/Pod/Perldoc/ToMan.pm
index 4319122..f697e5c 100644
--- a/lib/Pod/Perldoc/ToMan.pm
+++ b/lib/Pod/Perldoc/ToMan.pm
@@ -60,6 +60,10 @@ sub parse_from_file {
unless -e $pod2man;
}
+ eval { require Pod::Man };
+ $switches .= " --utf8"
+ if (!$@ && $Pod::Man::VERSION >= 2.18);
+
my $command = "$pod2man $switches --lax $file | $render -man";
# no temp file, just a pipe!