From fenner@research.att.com

Hi,

  pod2man doesn't handle multiple =over's very well; it keeps the
indentation of the =item label the same so it's hard to tell what
goes with what; the source​:

=item SNMP​::Varbind

..text

=over

=item <obj>

..text

=over

=item 1

..text

produces​:

  SNMP​::Varbind
  represents a single MIB object to get or set,
  implemented as a blessed reference to a 4 element
  array; [<obj>, <iid>, <val>, <type>].

  <obj> one of the following forms​:

  1) leaf identifier (e.g., 'sysDescr') assumed
  to be unique for practical purposes

I find this extremely hard to read, so I changed it to use the
man macros' indentation features as follows​:

  SNMP​::Varbind
  represents a single MIB object to get or set,
  implemented as a blessed reference to a 4 element
  array; [<obj>, <iid>, <val>, <type>].

  <obj>
  one of the following forms​:

  1) leaf identifier (e.g., 'sysDescr') assumed
  to be unique for practical purposes

I find this to be much more readable. It's a little hokey,
since it relies on nroff to do the math since I was too lazy
to unquote the math in the .Ip, but it at least gives a starting
point.

  Bill

--- /usr/bin/pod2man	Wed Sep  8 00:32:02 1999
+++ /tmp/pod2man	Thu Sep 30 18:18:01 1999
@@ -877,10 +877,16 @@
 	elsif ($Cmd eq 'over') {
 	    push(@indent,$indent);
 	    $indent += ($_ + 0) || 5;
+	    if ($#indent > 0) {
+		print ".RS ", $indent[$#indent] - $indent[$#indent - 1], "\n";
+	    }
 	}
 	elsif ($Cmd eq 'back') {
 	    $indent = pop(@indent);
 	    warn "$0: Unmatched =back in paragraph $. of $ARGV\n" unless defined $indent;
+	    if ($#indent >= 0) {
+		print ".RE\n";
+	    }
 	    $needspace = 1;
 	}
 	elsif ($Cmd eq 'item') {
@@ -890,7 +896,7 @@
 	    s/\\\*\(L"([^"]+?)""/'$1'/g;
 	    s/[^"]""([^"]+?)""[^"]/'$1'/g;
 	    # here do something about the $" in perlvar?
-	    print STDOUT qq{.Ip "$_" $indent\n};
+	    print STDOUT qq{.Ip "$_" $indent-$indent[$#indent]\n};
       push(@Indices, qq{.IX Item "$_"\n});
 	}
 	elsif ($Cmd eq 'pod') {

Site configuration information for perl 5.00503:

Configured by markm at $Date: 1999/05/05 19:42:40 $.

Summary of my perl5 (5.0 patchlevel 5 subversion 3) configuration:
  Platform:
    osname=freebsd, osvers=4.0-current, archname=i386-freebsd
    uname='freebsd freefall.freebsd.org 4.0-current freebsd 4.0-current #0: $Date: 1999/05/05 19:42:40 $'
    hint=recommended, useposix=true, d_sigaction=define
    usethreads=undef useperlio=undef d_sfio=undef
  Compiler:
    cc='cc', optimize='undef', gccversion=egcs-2.91.66 19990314 (egcs-1.1.2 release)
    cppflags=''
    ccflags =''
    stdchar='char', d_stdstdio=undef, usevfork=true
    intsize=4, longsize=4, ptrsize=4, doublesize=8
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
    alignbytes=4, usemymalloc=n, prototype=define
  Linker and Libraries:
    ld='cc', ldflags ='-Wl,-E'
    libpth=/usr/lib
    libs=-lm -lc -lcrypt
    libc=/usr/lib/libc.so, so=so, useshrplib=true, libperl=libperl.so.3
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' '
    cccdlflags='-DPIC -fpic', lddlflags='-shared'

Locally applied patches:
    


@INC for perl 5.00503:
    /usr/libdata/perl/5.00503/mach
    /usr/libdata/perl/5.00503
    /usr/local/lib/perl5/site_perl/5.005/i386-freebsd
    /usr/local/lib/perl5/site_perl/5.005
    .


Environment for perl 5.00503:
    HOME=/home/fenner
    LANG (unset)
    LANGUAGE (unset)
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/home/fenner/bin:/home/fenner/bin/freebsd:/home/fenner/bin/mailcode:/bin:/usr/bin:/sbin:/usr/sbin:/usr/X11R6/bin:/usr/local/bin
    PERL_BADLANG (unset)
    SHELL=/bin/csh

From [Unknown Contact. See original ticket]

Bill Fenner <fenner@​research.att.com> writes​:

pod2man doesn't handle multiple =over's very well; it keeps the
indentation of the =item label the same so it's hard to tell what goes
with what; the source​:

This has been fixed in my proposed replacement for pod2man. If you want
to try it out, you can download podlators from modules/by-module/Pod on
CPAN. Your fix looks like it solves the immediate problem, but on at
least some man implementations you'll find that there's a weird
interaction between .Ip and .RS/.RE that will require another .RS/.RE
pair.

--
Russ Allbery (rra@​stanford.edu) <URL​:http​://www.eyrie.org/~eagle/>