From urban@ast.lmco.com

Pod2latex does not correctly generate latex files.

Below is a change log entry and a patch that allows pod2latex to correctly
generate latex files from pod pages.

D. S. Urban
email : urban@​ast.lmco.com

To be the person, you must know the person. To know the person, you must
understand the person. To understand the person, you must listen. To listen,
you must open your mind and put aside all preconceived ideas and notions.

All opinions expressed are my own not that of my employer

Summary of my perl5 (revision 5.0 version 6 subversion 0) configuration​:
  Platform​:
  osname=hpux, osvers=10.20, archname=PA-RISC1.1
  uname='hp-ux spica b.10.20 a 9000735 2008140532 two-user license '
  config_args='-Dcc=gcc -Dprefix=/home/urban/local/hp'
  hint=recommended, useposix=true, d_sigaction=define
  usethreads=undef use5005threads=undef useithreads=undef
usemultiplicity=undef
  useperlio=undef d_sfio=undef uselargefiles=undef
  use64bitint=undef use64bitall=undef uselongdouble=undef usesocks=undef
  Compiler​:
  cc='gcc', optimize='-O0', gccversion=2.96 20000103 (experimental)
  cppflags='-D_HPUX_SOURCE -L/lib/pa1.1 -DUINT32_MAX_BROKEN
-fno-strict-aliasing'
  ccflags ='-D_HPUX_SOURCE -L/lib/pa1.1 -DUINT32_MAX_BROKEN
-fno-strict-aliasing'
  stdchar='unsigned char', d_stdstdio=define, usevfork=false
  intsize=4, longsize=4, ptrsize=4, doublesize=8
  d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=8
  ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t',
lseeksize=4
  alignbytes=8, usemymalloc=y, prototype=define
  Linker and Libraries​:
  ld='ld', ldflags ='-L/usr/local/lib -L/home/urban/local/hp/lib'
  libpth=/usr/local/lib /lib /usr/lib /usr/ccs/lib /home/urban/local/hp/lib
  libs=-lnsl_s -lndbm -ldld -lm -lc -lndir -lcrypt -lsec
  libc=/lib/libc.sl, so=sl, useshrplib=false, libperl=libperl.a
  Dynamic Linking​:
  dlsrc=dl_hpux.xs, dlext=sl, d_dlsymun=undef, ccdlflags='-Wl,-E
-Wl,-B,deferred '
  cccdlflags='-fpic', lddlflags='-b -L/usr/local/lib
-L/home/urban/local/hp/lib'

Characteristics of this binary (from libperl)​:
  Compile-time options​:
  Built under hpux
  Compiled at Apr 17 2000 15​:02​:34
  @​INC​:
  /home/urban/local/hp/lib/perl5/5.6.0/PA-RISC1.1
  /home/urban/local/hp/lib/perl5/5.6.0
  /home/urban/local/hp/lib/perl5/site_perl/5.6.0/PA-RISC1.1
  /home/urban/local/hp/lib/perl5/site_perl/5.6.0
  /home/urban/local/hp/lib/perl5/site_perl/5.005/PA-RISC1.1
  /home/urban/local/hp/lib/perl5/site_perl/5.005
  /home/urban/local/hp/lib/perl5/site_perl
  .

-------------------------- Change Log entry ------------------------------------

2000-04-17 D. Scott Urban <urban@​ast.lmco.com>

  * pod2latex.PL​: Added commands and uncommented lines to allow pod2latex to
  generate a correct latex file.

Index pod2latex.PL

diff -c -3 -p pod2latex.PL.old pod2latex.PL
*** pod2latex.PL.old Tue Apr 18 09​:10​:48 2000
--- pod2latex.PL Tue Apr 18 09​:22​:08 2000
*************** while (<POD>) {
*** 505,510 ****
--- 505,511 ----
  }
 
  print LATEX "\n";
+ print LATEX "\\end{document}\n";
  close(POD);
  close(LATEX);
 
*************** close(LATEX);
*** 512,524 ****
  #########################################################################
 
  sub do_hdr {
  print LATEX "% LaTeX document produced by pod2latex from \"$pod.pod\".\n";
  print LATEX "% The followings need be defined in the preamble of this
document​:\n";
! print LATEX "%\\def\\C++{{\\rm
C\\kern-.05em\\raise.3ex\\hbox{\\footnotesize ++}}}\n";
! print LATEX "%\\def\\underscore{\\leavevmode\\kern.04em\\vbox{\\hrule
width 0.4em height 0.3pt}}\n";
! print LATEX "%\\setlength{\\parindent}{0pt}\n";
  print LATEX "\n";
  $podq = &escape_tex_specials("\U$pod\E");
  print LATEX "\\section{$podq}%\n";
  print LATEX "\\index{$podq}";
  print LATEX "\n";
--- 513,528 ----
  #########################################################################
 
  sub do_hdr {
+ print LATEX "\\documentclass{article}\n";
+ print LATEX "\\normalsize\n";
  print LATEX "% LaTeX document produced by pod2latex from \"$pod.pod\".\n";
  print LATEX "% The followings need be defined in the preamble of this
document​:\n";
! print LATEX "\\def\\C++{{\\rm
C\\kern-.05em\\raise.3ex\\hbox{\\footnotesize ++}}}\n";
! print LATEX "\\def\\underscore{\\leavevmode\\kern.04em\\vbox{\\hrule width
0.4em height 0.3pt}}\n";
! print LATEX "\\setlength{\\parindent}{0pt}\n";
  print LATEX "\n";
  $podq = &escape_tex_specials("\U$pod\E");
+ print LATEX "\\begin{document}\n";
  print LATEX "\\section{$podq}%\n";
  print LATEX "\\index{$podq}";
  print LATEX "\n";

From [Unknown Contact. See original ticket]

'David Scott Urban (lists.p5p)​:

Pod2latex does not correctly generate latex files.

Yes, it does. However, it doesn't generate complete LaTeX files.
I believe there are good reasons for this, in that it makes it easy to
include LaTeX generated from pod2latex in another file, and it makes it
easy to add a wrapper around the Perl documentation so that it will be
produced in whatever style you want. It also means you can process
several - or even all of - pod files and have them form a single
document, much like roffitall does.

Perhaps we should do either or all of​:
  i) Ship a sample wrapper which contains the LaTeX code in your
  patch, plus \include{...}
  ii) Make it an optional flag to pod2latex to generate a complete
  document or generate a wrapper for the appropriate file.
  iii) Ship a texitall like roffitall which converts all the
  documents, runs latex on them and leaves you with a single DVI file.

Any ideas which way to go?

From [Unknown Contact. See original ticket]

Pod2latex does not correctly generate latex files.

Its not meant to!

Below is a change log entry and a patch that allows pod2latex to correctly
generate latex files from pod pages.

Its meant to generate .tex files which can be included in a latex file.

That's why the output includes some comments saying what should be defined
before \begin{document} and why the output consists of a single \section.

Robin

From @timj

Pod2latex does not correctly generate latex files.

I think this was a deliberate design choice. If you want a version of
pod2latex that will do this (and much more) then can you please try
the Pod​::LaTeX module from CPAN -- this uses Pod​::Parser (rather than
doing it all 'in house' and can, optionally, be made to combine multiple
pods into a single output file with correct start/end latex code
(and with an option to rewrite =head1 NAME sections so that they are more
readable in latex.)

I would be interested in your comments. I would like to get this version
of pod2latex into the core so that the old one can be retired.

From @timj

Simon,

Perhaps we should do either or all of​:
i) Ship a sample wrapper which contains the LaTeX code in your
patch, plus \include{...}
ii) Make it an optional flag to pod2latex to generate a complete
document or generate a wrapper for the appropriate file.
iii) Ship a texitall like roffitall which converts all the
documents, runs latex on them and leaves you with a single DVI file.

Any ideas which way to go?

<ADVERT>
pod2latex from Pod​::LaTeX already does points (ii) [command line
option, can wrap multiple input files into a single latex file] and (iii)
since it uses Pod​::Find you simply need to specify the top level directory
and it finds all pods. Does not need a separate texitall style script.
</ADVERT>

From [Unknown Contact. See original ticket]

I think it would be a good idea to replace the existing pod2latex with this
version. It is quite a bit more functionality than the present version. Your
version is that next steps I would have been trying to take in making it better.
So at least, I don't have to try and re-invent the wheel.

I will check things out more completely next time before deciding if there is a
problem or not.

Thanks for all the quick responses.

Scott

Pod2latex does not correctly generate latex files.

I think this was a deliberate design choice. If you want a version of
pod2latex that will do this (and much more) then can you please try
the Pod​::LaTeX module from CPAN -- this uses Pod​::Parser (rather than
doing it all 'in house' and can, optionally, be made to combine multiple
pods into a single output file with correct start/end latex code
(and with an option to rewrite =head1 NAME sections so that they are more
readable in latex.)

I would be interested in your comments. I would like to get this version
of pod2latex into the core so that the old one can be retired.

--
Tim Jenness
JCMT software engineer/Support scientist
http​://www.jach.hawaii.edu/~timj

From [Unknown Contact. See original ticket]

'David Scott Urban <urban@​ast.lmco.com> writes​:

I think it would be a good idea to replace the existing pod2latex with
this version. It is quite a bit more functionality than the present
version.

That's definitely the long-term intention, at least as far as I'm
concerned. The pod2latex script that currently comes with Perl is quite
old.

From @rspier

Marking as resolved. Recent perl's pod2latex in the core is synced with
the CPAN version. Anyway, use the CPAN version if you need newer
features, and report bugs here​:
http​://rt.cpan.org/NoAuth/Bugs.html?Dist=Pod-LaTeX

@rspier - Status changed from 'open' to 'resolved'