Upgrade to Pod::LaTeX 0.57

p4raw-id: //depot/perl@22912

4 files changed, 222 insertions, 52 deletions

diff --git a/MANIFEST b/MANIFEST
index 609919dbf0..4ccdbfc80f 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1590,6 +1590,7 @@ lib/Pod/t/text-errors.t		podlators test
 lib/Pod/t/text-options.t		podlators test
 lib/Pod/t/text.t		podlators test
 lib/Pod/t/Usage.t		See if Pod::Usage works
+lib/Pod/t/user.t		See if Pod::LaTeX works
 lib/Pod/t/utils.t		Test for Pod::ParseUtils
 lib/Pod/Usage.pm		Pod-Parser - print usage messages
 lib/pwd.pl			Routines to keep track of PWD environment variable
diff --git a/lib/Pod/LaTeX.pm b/lib/Pod/LaTeX.pm
index 6979666e9b..95be1b301d 100644
--- a/lib/Pod/LaTeX.pm
+++ b/lib/Pod/LaTeX.pm
@@ -33,7 +33,7 @@ use Carp;
 
 use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
 
-$VERSION = '0.55';
+$VERSION = '0.56';
 
 # Definitions of =headN -> latex mapping
 @LatexSections = (qw/
@@ -856,7 +856,9 @@ on what these methods require.
 
 =item B<begin_pod>
 
-Writes the C<latex> preamble if requested.
+Writes the C<latex> preamble if requested. Only writes something
+if AddPreamble is true. Writes a standard header unless a UserPreamble
+is defined.
 
 =cut
 
@@ -881,40 +883,42 @@ __TEX_COMMENT__
   # If the caller has supplied one then we just use that
 
   my $preamble = '';
-  if (defined $self->UserPreamble) {
 
-    $preamble = $self->UserPreamble;
+  if ($self->AddPreamble) {
 
-    # Add the description of where this came from
-    $preamble .=  "\n$comment";
-    
+    if (defined $self->UserPreamble) {
 
-  } elsif ($self->AddPreamble) {
-    # Write our own preamble
+      $preamble = $self->UserPreamble;
 
-    # Code to initialise index making
-    # Use an array so that we can prepend comment if required
-    my @makeidx = (
-		   '\usepackage{makeidx}',
-		   '\makeindex',
-		  );
+      # Add the description of where this came from
+      $preamble .=  "\n$comment\n%%  Preamble supplied by user.\n\n";
 
-    unless ($self->MakeIndex) {
-      foreach (@makeidx) {
-	$_ = '%% ' . $_;
-      }
-    }
-    my $makeindex = join("\n",@makeidx) . "\n";
+    } else {
+
+      # Write our own preamble
+
+      # Code to initialise index making
+      # Use an array so that we can prepend comment if required
+      my @makeidx = (
+		     '\usepackage{makeidx}',
+		     '\makeindex',
+		    );
 
+      unless ($self->MakeIndex) {
+	foreach (@makeidx) {
+	  $_ = '%% ' . $_;
+	}
+      }
+      my $makeindex = join("\n",@makeidx) . "\n";
 
-    # Table of contents
-    my $tableofcontents = '\tableofcontents';
+      # Table of contents
+      my $tableofcontents = '\tableofcontents';
 
-    $tableofcontents = '%% ' . $tableofcontents
-      unless $self->TableOfContents;
+      $tableofcontents = '%% ' . $tableofcontents
+	unless $self->TableOfContents;
 
-    # Roll our own
-    $preamble = << "__TEX_HEADER__";
+      # Roll our own
+      $preamble = << "__TEX_HEADER__";
 \\documentclass{article}
 \\usepackage[T1]{fontenc}
 \\usepackage{textcomp}
@@ -929,6 +933,7 @@ $tableofcontents
 
 __TEX_HEADER__
 
+    }
   }
 
   # Write the header (blank if none)
@@ -942,7 +947,8 @@ __TEX_HEADER__
 
 =item B<end_pod>
 
-Write the closing C<latex> code.
+Write the closing C<latex> code. Only writes something if AddPostamble
+is true. Writes a standard header unless a UserPostamble is defined.
 
 =cut
 
@@ -952,23 +958,23 @@ sub end_pod {
   # End string
   my $end = '';
 
-  # Use the user version of the postamble if deinfed
-  if (defined $self->UserPostamble) {
-    $end = $self->UserPostamble;
+  # Use the user version of the postamble if defined
+  if ($self->AddPostamble) {
 
-    $self->_output($end);
+    if (defined $self->UserPostamble) {
+      $end = $self->UserPostamble;
 
-  } elsif ($self->AddPostamble) {
+    } else {
 
-    # Check for index
-    my $makeindex = '\printindex';
+      # Check for index
+      my $makeindex = '\printindex';
 
-    $makeindex = '%% '. $makeindex  unless $self->MakeIndex;
+      $makeindex = '%% '. $makeindex  unless $self->MakeIndex;
 
-    $end = "$makeindex\n\n\\end{document}\n";
+      $end = "$makeindex\n\n\\end{document}\n";
+    }
   }
 
-
   $self->_output($end);
 
 }
@@ -1837,20 +1843,21 @@ L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
 
 =head1 AUTHORS
 
-Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
+Tim Jenness E<lt>tjenness@cpan.orgE<gt>
 
 Bug fixes and improvements have been received from: Simon Cozens
 E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
 E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
 E<lt>marcel@codewerk.comE<gt>, Hugh S Myers
 E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam
-E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>
-and Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>.
+E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>,
+Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt> and
+Adriano Rodrigues Ferreira E<lt>ferreira@triang.com.brE<gt>.
 
 
 =head1 COPYRIGHT
 
-Copyright (C) 2000-2003 Tim Jenness. All Rights Reserved.
+Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.
 
 This program is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
@@ -1859,7 +1866,7 @@ it under the same terms as Perl itself.
 
 =head1 REVISION
 
-$Id: LaTeX.pm,v 1.17 2003/04/05 21:25:49 timj Exp $
+$Id: LaTeX.pm,v 1.18 2004/03/08 02:22:43 timj Exp $
 
 =end __PRIVATE__
 
diff --git a/lib/Pod/t/user.t b/lib/Pod/t/user.t
new file mode 100644
index 0000000000..04776de5ac
--- /dev/null
+++ b/lib/Pod/t/user.t
@@ -0,0 +1,104 @@
+#!perl
+
+# Purpose: test UserPreamble and UserPostamble
+# It's a minor variation of 'pod2latex.t',
+# subject to the same limitations.
+#   Variant provided by
+#       Adriano Rodrigues Ferreira <ferreira@triang.com.br>
+
+use Test;
+use strict;
+
+BEGIN { plan tests => 17 }
+
+use Pod::LaTeX;
+
+# The link parsing changed between v0.22 and v0.30 of Pod::ParseUtils
+use Pod::ParseUtils;
+my $linkver = $Pod::ParseUtils::VERSION;
+
+# Set up an END block to remove the test output file
+END {
+  unlink "test.tex";
+};
+
+ok(1);
+
+# First thing to do is to read the expected output from
+# the DATA filehandle and store it in a scalar.
+# Do this until we read an =pod
+my @reference;
+while (my $line = <DATA>) {
+  last if $line =~ /^=pod/;
+  push(@reference,$line);
+}
+
+my $user_preamble = <<PRE;
+
+\\documentclass{article}
+
+\\begin{document}
+PRE
+
+my $user_postamble = <<POST;
+\\end{document}
+
+POST
+
+# Create a new parser
+my %params = (
+	UserPreamble => $user_preamble,
+	UserPostamble => $user_postamble
+);
+
+my $parser = Pod::LaTeX->new(%params);
+ok($parser);
+
+# Create an output file
+open(OUTFH, "> test.tex" ) or die "Unable to open test tex file: $!\n";
+
+# Read from the DATA filehandle and write to a new output file
+# Really want to write this to a scalar
+$parser->parse_from_filehandle(\*DATA,\*OUTFH);
+
+close(OUTFH) or die "Error closing OUTFH test.tex: $!\n";
+
+# Now read in OUTFH and compare
+open(INFH, "< test.tex") or die "Unable to read test tex file: $!\n";
+my @output = <INFH>;
+
+ok(@output, @reference);
+
+for my $i (0..$#reference) {
+  next if $reference[$i] =~ /^%%/; # skip timestamp comments
+  ok($output[$i], $reference[$i]);
+}
+
+close(INFH) or die "Error closing INFH test.tex: $!\n";
+
+
+__DATA__
+
+\documentclass{article}
+
+\begin{document}
+
+%%  Latex generated from POD in document (unknown)
+%%  Using the perl module Pod::LaTeX
+%%  Converted on Wed Jan 14 19:04:22 2004
+
+%%  Preamble supplied by user.
+
+\section{POD\label{POD}\index{POD}}
+
+
+This is a POD file, very simple. \textit{Bye}.
+
+\end{document}
+
+=pod
+
+=head1 POD
+
+This is a POD file, very simple. I<Bye>.
+
diff --git a/pod/pod2latex.PL b/pod/pod2latex.PL
index 6b4dc4c86e..9838edc889 100644
--- a/pod/pod2latex.PL
+++ b/pod/pod2latex.PL
@@ -43,8 +43,20 @@ use Pod::Find qw/ pod_find /;
 use Pod::Usage;
 use Getopt::Long;
 use File::Basename;
-
-my $VERSION = "1.00";
+use Symbol;
+
+my $VERSION = "1.01";
+
+# return the entire contents of a text file
+# whose name is given as argument
+sub _get {
+    my $fn = shift;
+    my $infh = gensym;
+    open $infh, $fn
+        or die "Could not open file $fn: $!\n";
+    local $/;
+    return <$infh>;
+}
 
 # Read command line arguments
 
@@ -57,7 +69,14 @@ my %options = (
 	       "verbose" => 0,
 	       "modify" => 0,
 	       "h1level" => 1,  # section is equivalent to H1
+	       "preamble" => [],
+	       "postamble" => [],
 	      );
+# "prefile" is just like "preamble", but the argument 
+# comes from the file named by the argument
+$options{"prefile"} = sub { shift; push @{$options{"preamble"}}, _get(shift) };
+# the same between "postfile" and "postamble"
+$options{"postfile"} = sub { shift; push @{$options{"postamble"}}, _get(shift) };
 
 GetOptions(\%options, 
 	   "help",
@@ -68,6 +87,10 @@ GetOptions(\%options,
 	   "out=s",
 	   "modify",
 	   "h1level=i",
+	   "preamble=s@",
+	   "postamble=s@",
+	   "prefile=s", 
+	   "postfile=s"
 	  ) || pod2usage(2);
 
 pod2usage(1)  if ($options{help});
@@ -98,6 +121,14 @@ if ($#pods == -1) {
   exit;
 }
 
+# Only want to override the preamble and postamble if we have
+# been given values.
+my %User;
+$User{UserPreamble} = join("\n", @{$options{'preamble'}})
+  if ($options{preamble} && @{$options{preamble}});
+$User{UserPostamble} = join("\n", @{$options{'postamble'}})
+  if ($options{postamble} && @{$options{postamble}});
+
 
 
 # If $options{'out'} is set we are processing to a single output file
@@ -133,6 +164,7 @@ if ($multi_documents) {
 				  UniqueLabels => $options{'modify'},
 				  Head1Level => $options{'h1level'},
 				  LevelNoNum => $options{'h1level'} + 1,
+                                  %User,
 				 );
 
       # Select sections if supplied
@@ -150,7 +182,7 @@ if ($multi_documents) {
 
   }
 } else {
-  
+
   # Case where we want everything to be in a single document
 
   # Need to open the output file ourselves
@@ -158,7 +190,6 @@ if ($multi_documents) {
   $output .= '.tex' unless $output =~ /\.tex$/;
 
   # Use auto-vivified file handle in perl 5.6
-  use Symbol;
   my $outfh = gensym;
   open ($outfh, ">$output") || die "Could not open output file: $!\n";
 
@@ -202,6 +233,7 @@ if ($multi_documents) {
 				  AddPostamble => $postamble,
 				  Head1Level => $options{'h1level'},
 				  LevelNoNum => $options{'h1level'} + 1,
+                                  %User
 				 );
 
       # Store the file name for error messages
@@ -251,6 +283,8 @@ pod2latex - convert pod documentation to latex format
 
   pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir
 
+  pod2latex -prefile h.tex -postfile t.tex my.pod
+
 =head1 DESCRIPTION
 
 C<pod2latex> is a program to convert POD format documentation
@@ -319,6 +353,30 @@ Print the manual page and exit.
 
 Print information messages as each document is processed.
 
+=item B<-preamble>
+
+A user-supplied preamble for the LaTeX code. Multiple values
+are supported and appended in order separated by "\n".
+See B<-prefile> for reading the preamble from a file.
+
+=item B<-postamble>
+
+A user supplied postamble for the LaTeX code. Multiple values
+are supported and appended in order separated by "\n".
+See B<-postfile> for reading the postamble from a file.
+
+=item B<-prefile>
+
+A user-supplied preamble for the LaTeX code to be read from the
+named file. Multiple values are supported and appended in
+order. See B<-preamble>.
+
+=item B<-postfile>
+
+A user-supplied postamble for the LaTeX code to be read from the
+named file. Multiple values are supported and appended in
+order. See B<-postamble>.
+
 =back
 
 =head1 BUGS
@@ -327,14 +385,14 @@ Known bugs are:
 
 =over 4
 
-=item * 
+=item *
 
 Cross references between documents are not resolved when multiple
 pod documents are converted into a single output C<latex> file.
 
-=item * 
+=item *
 
-Functions and variables are not automatically recognized 
+Functions and variables are not automatically recognized
 and they will therefore not be marked up in any special way
 unless instructed by an explicit pod command.
 
@@ -346,12 +404,12 @@ L<Pod::LaTeX>
 
 =head1 AUTHOR
 
-Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
+Tim Jenness E<lt>tjenness@cpan.orgE<gt>
 
 This program is free software; you can redistribute it
 and/or modify it under the same terms as Perl itself.
 
-Copyright (C) 2000, 2003 Tim Jenness. All Rights Reserved.
+Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved.
 
 =cut