Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

pod2man doesn't handle multiple =over's very well #665

Closed
p5pRT opened this issue Sep 30, 1999 · 2 comments
Closed

pod2man doesn't handle multiple =over's very well #665

p5pRT opened this issue Sep 30, 1999 · 2 comments

Comments

@p5pRT
Copy link

@p5pRT p5pRT commented Sep 30, 1999

Migrated from rt.perl.org#1545 (status was 'resolved')

Searchable as RT1545$

@p5pRT
Copy link
Author

@p5pRT p5pRT commented Sep 30, 1999

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

Inline Patch
--- /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') {
Perl Info


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

@p5pRT
Copy link
Author

@p5pRT p5pRT commented Oct 1, 1999

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/>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant