Package: perl
Version: 5.8.8-11
Severity: normal
Tags: patch
File: /usr/bin/pod2man
The file foo.pod below processed with
pod2man foo.pod | man -l -
produces
Some text.
Some text.
where I hoped it would include the two =head2 lines as headings.
I noticed this in the docs of Gtk2::Ex::DBI (from cpan) where the
"'destroy' method" subheading under the BUGS section doesn't come out.
I think the troff generated by pod2man ends up with the heading text at
the start of a line, so a leading . or ' is interpreted as a request.
Apparently groff in compatibility mode ignores unknown requests, but you
can see errors with say
pod2man foo.pod | groff -man >/dev/null
gives
<standard input>:133: warning: `destroy'' not defined (probable missing
space after `de')
<standard input>:136: warning: `deb' not defined (probable missing
space after `de')
I think pod2man's .Sh macro can avoid the problem with a \& zero-width
space, per diff below. This would be like what groff's .SH does
(/usr/share/groff/1.18.1/tmac/an-old.tmac).
Although .Sh currently has \fB as the start of the line, apparently
troff, and groff in compatibility mode, will "see through" such font
settings and consider what follows to still be at the start of the line.
The groff manual under "Implementation Differences" has a note on that.
-- System Information:
Debian Release: lenny/sid
APT prefers unstable
APT policy: (500, 'unstable')
Architecture: i386 (i586)
Kernel: Linux 2.6.22-2-486
Locale: LANG=en_AU, LC_CTYPE=en_AU (charmap=ISO-8859-1)
Shell: /bin/sh linked to /bin/dash
Versions of packages perl depends on:
ii libc6 2.6.1-2 GNU C Library: Shared libraries
ii libdb4.6 4.6.21-4 Berkeley v4.6 Database Libraries [
ii libgdbm3 1.8.3-3 GNU dbm database routines (runtime
ii perl-base 5.8.8-11 The Pathologically Eclectic Rubbis
ii perl-modules 5.8.8-11 Core Perl modules
Versions of packages perl recommends:
ii perl-doc 5.8.8-7 Perl documentation
-- no debconf information
=head2 'destroy' method
Some text.
=head2 .deb file handling
Some text.
--- Man.pm.old 2007-10-26 19:38:05.000000000 +1000
+++ Man.pm 2007-10-26 19:37:49.000000000 +1000
@@ -56,7 +56,7 @@
.if t .Sp
.ne 5
.PP
-\fB\\$1\fR
+\&\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
