develooper Front page | perl.perl5.porters | Postings from May 2008

[perl #53910] pod2man loses =head2 starting ' or .

Kevin Ryde
May 9, 2008 06:40
[perl #53910] pod2man loses =head2 starting ' or .
Message ID:
# New Ticket Created by  Kevin Ryde 
# Please include the string:  [perl #53910]
# in the subject line of all future correspondence about this issue. 
# <URL: >

The file foo.pod below processed with

	pod2man foo.pod | man -l -


	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.
Groff in compatibility mode ignores unknown requests apparently, but you
can see errors with say

	pod2man foo.pod | groff -man >/dev/null


	<standard input>:140: warning: `destroy'' not defined (probable missing space after `de')
	<standard input>:143: 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 (in

Although .Sh has \fB as the start of the line, apparently troff, and
that includes groff in compatibility mode, will "see through" such a
font setting and consider what follows to still be at the start of the
line.  The groff manual under "Implementation Differences" has a note on

[Please do not change anything below this line]
Site configuration information for perl 5.10.0:

Configured by Debian Project at Thu May  1 02:26:44 UTC 2008.

Summary of my perl5 (revision 5 version 10 subversion 0) configuration:
    osname=linux, osvers=, archname=i486-linux-gnu-thread-multi
    uname='linux ninsei #1 smp preempt fri apr 18 15:36:09 pdt 2008 i686 gnulinux '
    config_args='-Dusethreads -Duselargefiles -Dccflags=-DDEBIAN -Dcccdlflags=-fPIC -Darchname=i486-linux-gnu -Dprefix=/usr -Dprivlib=/usr/share/perl/5.10 -Darchlib=/usr/lib/perl/5.10 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/perl5 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.10.0 -Dsitearch=/usr/local/lib/perl/5.10.0 -Dman1dir=/usr/share/man/man1 -Dman3dir=/usr/share/man/man3 -Dsiteman1dir=/usr/local/man/man1 -Dsiteman3dir=/usr/local/man/man3 -Dman1ext=1 -Dman3ext=3perl -Dpager=/usr/bin/sensible-pager -Uafs -Ud_csh -Ud_ualarm -Uusesfio -Uusenm -DDEBUGGING=-g -Doptimize=-O2 -Duseshrplib -Dd_dosuid -des'
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=define, usemultiplicity=define
    useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
    use64bitint=undef, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
    cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-O2 -g',
    cppflags='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fno-strict-aliasing -pipe -I/usr/local/include'
    ccversion='', gccversion='4.2.3 (Debian 4.2.3-3)', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=4, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib /usr/lib64
    libs=-lgdbm -lgdbm_compat -ldb -ldl -lm -lpthread -lc -lcrypt
    perllibs=-ldl -lm -lpthread -lc -lcrypt
    libc=/lib/, so=so, useshrplib=true,
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
    cccdlflags='-fPIC', lddlflags='-shared -O2 -g -L/usr/local/lib'

Locally applied patches:

@INC for perl 5.10.0:
    . Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About