| #!/usr/local/bin/perl |
| |
| use Config; |
| use File::Basename qw(&basename &dirname); |
| use Cwd; |
| |
| # List explicitly here the variables you want Configure to |
| # generate. Metaconfig only looks for shell variables, so you |
| # have to mention them as if they were shell variables, not |
| # %Config entries. Thus you write |
| # $startperl |
| # to ensure Configure will look for $Config{startperl}. |
| |
| # This forces PL files to create target in same directory as PL file. |
| # This is so that make depend always knows where to find PL derivatives. |
| $origdir = cwd; |
| chdir dirname($0); |
| $file = basename($0, '.PL'); |
| $file .= '.com' if $^O eq 'VMS'; |
| |
| open OUT,">$file" or die "Can't create $file: $!"; |
| |
| print "Extracting $file (with variable substitutions)\n"; |
| |
| # In this section, perl variables will be expanded during extraction. |
| # You can use $Config{...} to use Configure variables. |
| |
| print OUT <<"!GROK!THIS!"; |
| $Config{startperl} |
| eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' |
| if \$running_under_some_shell; |
| !GROK!THIS! |
| |
| # In the following, perl variables are not expanded during extraction. |
| |
| print OUT <<'!NO!SUBS!'; |
| |
| # pod2latex conversion program |
| |
| use strict; |
| use Pod::LaTeX; |
| use Pod::Find qw/ pod_find /; |
| use Pod::Usage; |
| use Getopt::Long; |
| use File::Basename; |
| 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 |
| |
| my %options = ( |
| "help" => 0, |
| "man" => 0, |
| "sections" => [], |
| "full" => 0, |
| "out" => undef, |
| "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", |
| "man", |
| "verbose", |
| "full", |
| "sections=s@", |
| "out=s", |
| "modify", |
| "h1level=i", |
| "preamble=s@", |
| "postamble=s@", |
| "prefile=s", |
| "postfile=s" |
| ) || pod2usage(2); |
| |
| pod2usage(1) if ($options{help}); |
| pod2usage(-verbose => 2) if ($options{man}); |
| |
| |
| # Read all the files from the command line |
| my @files = @ARGV; |
| |
| # Now find which ones are real pods and convert |
| # directories to their contents. |
| |
| # Extract the pods from each arg since some of them might |
| # be directories |
| # This is not as efficient as using pod_find to search through |
| # everything at once but it allows us to preserve the order |
| # supplied by the user |
| |
| my @pods; |
| foreach my $arg (@files) { |
| my %pods = pod_find($arg); |
| push(@pods, sort keys %pods); |
| } |
| |
| # Abort if nothing to do |
| if ($#pods == -1) { |
| warn "None of the supplied Pod files actually exist\n"; |
| 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 |
| my $multi_documents; |
| if (exists $options{'out'} && defined $options{'out'}) { |
| $multi_documents = 0; |
| } else { |
| $multi_documents = 1; |
| } |
| |
| # If the output file is not specified it is assumed that |
| # a single output file is required per input file using |
| # a .tex extension rather than any existing extension |
| |
| if ($multi_documents) { |
| |
| # Case where we just generate one input per output |
| |
| foreach my $pod (@pods) { |
| |
| if (-f $pod) { |
| |
| my $output = $pod; |
| $output = basename($output, '.pm', '.pod','.pl') . '.tex'; |
| |
| # Create a new parser object |
| my $parser = new Pod::LaTeX( |
| AddPreamble => $options{'full'}, |
| AddPostamble => $options{'full'}, |
| MakeIndex => $options{'full'}, |
| TableOfContents => $options{'full'}, |
| ReplaceNAMEwithSection => $options{'modify'}, |
| UniqueLabels => $options{'modify'}, |
| Head1Level => $options{'h1level'}, |
| LevelNoNum => $options{'h1level'} + 1, |
| %User, |
| ); |
| |
| # Select sections if supplied |
| $parser->select(@{ $options{'sections'}}) |
| if @{$options{'sections'}}; |
| |
| # Derive the input file from the output file |
| $parser->parse_from_file($pod, $output); |
| |
| print "Written output to $output\n" if $options{'verbose'}; |
| |
| } else { |
| warn "File $pod not found\n"; |
| } |
| |
| } |
| } else { |
| |
| # Case where we want everything to be in a single document |
| |
| # Need to open the output file ourselves |
| my $output = $options{'out'}; |
| $output .= '.tex' unless $output =~ /\.tex$/; |
| |
| # Use auto-vivified file handle in perl 5.6 |
| my $outfh = gensym; |
| open ($outfh, ">$output") || die "Could not open output file: $!\n"; |
| |
| # Flag to indicate whether we have converted at least one file |
| # indicates how many files have been converted |
| my $converted = 0; |
| |
| # Loop over the input files |
| foreach my $pod (@pods) { |
| |
| if (-f $pod) { |
| |
| warn "Converting $pod\n" if $options{'verbose'}; |
| |
| # Open the file (need the handle) |
| # Use auto-vivified handle in perl 5.6 |
| my $podfh = gensym; |
| open ($podfh, "<$pod") || die "Could not open pod file $pod: $!\n"; |
| |
| # if this is the first file to be converted we may want to add |
| # a preamble (controlled by command line option) |
| my $preamble = 0; |
| $preamble = 1 if ($converted == 0 && $options{'full'}); |
| |
| # if this is the last file to be converted may want to add |
| # a postamble (controlled by command line option) |
| # relies on a previous pass to check existence of all pods we |
| # are converting. |
| my $postamble = ( ($converted == $#pods && $options{'full'}) ? 1 : 0 ); |
| |
| # Open parser object |
| # May want to start with a preamble for the first one and |
| # end with an index for the last |
| my $parser = new Pod::LaTeX( |
| MakeIndex => $options{'full'}, |
| TableOfContents => $preamble, |
| ReplaceNAMEwithSection => $options{'modify'}, |
| UniqueLabels => $options{'modify'}, |
| StartWithNewPage => $options{'full'}, |
| AddPreamble => $preamble, |
| AddPostamble => $postamble, |
| Head1Level => $options{'h1level'}, |
| LevelNoNum => $options{'h1level'} + 1, |
| %User |
| ); |
| |
| # Store the file name for error messages |
| # This is a kluge that breaks the data hiding of the object |
| $parser->{_INFILE} = $pod; |
| |
| # Select sections if supplied |
| $parser->select(@{ $options{'sections'}}) |
| if @{$options{'sections'}}; |
| |
| # Parse it |
| $parser->parse_from_filehandle($podfh, $outfh); |
| |
| # We have converted at least one file |
| $converted++; |
| |
| } else { |
| warn "File $pod not found\n"; |
| } |
| |
| } |
| |
| # Should unlink the file if we didn't convert anything! |
| # dont check for return status of unlink |
| # since there is not a lot to be done if the unlink failed |
| # and the program does not rely upon it. |
| unlink "$output" unless $converted; |
| |
| # If verbose |
| warn "Converted $converted files\n" if $options{'verbose'}; |
| |
| } |
| |
| exit; |
| |
| __END__ |
| |
| =head1 NAME |
| |
| pod2latex - convert pod documentation to latex format |
| |
| =head1 SYNOPSIS |
| |
| pod2latex *.pm |
| |
| pod2latex -out mytex.tex *.pod |
| |
| 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 |
| (L<perlpod>) into latex. It can process multiple input documents at a |
| time and either generate a latex file per input document or a single |
| combined output file. |
| |
| =head1 OPTIONS AND ARGUMENTS |
| |
| This section describes the supported command line options. Minimum |
| matching is supported. |
| |
| =over 4 |
| |
| =item B<-out> |
| |
| Name of the output file to be used. If there are multiple input pods |
| it is assumed that the intention is to write all translated output |
| into a single file. C<.tex> is appended if not present. If the |
| argument is not supplied, a single document will be created for each |
| input file. |
| |
| =item B<-full> |
| |
| Creates a complete C<latex> file that can be processed immediately |
| (unless C<=for/=begin> directives are used that rely on extra packages). |
| Table of contents and index generation commands are included in the |
| wrapper C<latex> code. |
| |
| =item B<-sections> |
| |
| Specify pod sections to include (or remove if negated) in the |
| translation. See L<Pod::Select/"SECTION SPECIFICATIONS"> for the |
| format to use for I<section-spec>. This option may be given multiple |
| times on the command line.This is identical to the similar option in |
| the C<podselect()> command. |
| |
| =item B<-modify> |
| |
| This option causes the output C<latex> to be slightly |
| modified from the input pod such that when a C<=head1 NAME> |
| is encountered a section is created containing the actual |
| pod name (rather than B<NAME>) and all subsequent C<=head1> |
| directives are treated as subsections. This has the advantage |
| that the description of a module will be in its own section |
| which is helpful for including module descriptions in documentation. |
| Also forces C<latex> label and index entries to be prefixed by the |
| name of the module. |
| |
| =item B<-h1level> |
| |
| Specifies the C<latex> section that is equivalent to a C<H1> pod |
| directive. This is an integer between 0 and 5 with 0 equivalent to a |
| C<latex> chapter, 1 equivalent to a C<latex> section etc. The default |
| is 1 (C<H1> equivalent to a latex section). |
| |
| =item B<-help> |
| |
| Print a brief help message and exit. |
| |
| =item B<-man> |
| |
| Print the manual page and exit. |
| |
| =item B<-verbose> |
| |
| 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 |
| |
| Known bugs are: |
| |
| =over 4 |
| |
| =item * |
| |
| Cross references between documents are not resolved when multiple |
| pod documents are converted into a single output C<latex> file. |
| |
| =item * |
| |
| 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. |
| |
| =back |
| |
| =head1 SEE ALSO |
| |
| L<Pod::LaTeX> |
| |
| =head1 AUTHOR |
| |
| 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, 2004 Tim Jenness. All Rights Reserved. |
| |
| =cut |
| |
| !NO!SUBS! |
| |
| close OUT or die "Can't close $file: $!"; |
| chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; |
| exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; |
| chdir $origdir; |