1#!/usr/local/bin/perl 2 3use Config; 4use File::Basename qw(&basename &dirname); 5use Cwd; 6 7# List explicitly here the variables you want Configure to 8# generate. Metaconfig only looks for shell variables, so you 9# have to mention them as if they were shell variables, not 10# %Config entries. Thus you write 11# $startperl 12# to ensure Configure will look for $Config{startperl}. 13 14# This forces PL files to create target in same directory as PL file. 15# This is so that make depend always knows where to find PL derivatives. 16$origdir = cwd; 17chdir dirname($0); 18$file = basename($0, '.PL'); 19$file .= '.com' if $^O eq 'VMS'; 20 21open OUT,">$file" or die "Can't create $file: $!"; 22 23print "Extracting $file (with variable substitutions)\n"; 24 25# In this section, perl variables will be expanded during extraction. 26# You can use $Config{...} to use Configure variables. 27 28print OUT <<"!GROK!THIS!"; 29$Config{startperl} 30 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' 31 if \$running_under_some_shell; 32!GROK!THIS! 33 34# In the following, perl variables are not expanded during extraction. 35 36print OUT <<'!NO!SUBS!'; 37 38# pod2latex conversion program 39 40use strict; 41use Pod::LaTeX; 42use Pod::Find qw/ pod_find /; 43use Pod::Usage; 44use Getopt::Long; 45use File::Basename; 46use Symbol; 47 48my $VERSION = "1.01"; 49 50# return the entire contents of a text file 51# whose name is given as argument 52sub _get { 53 my $fn = shift; 54 my $infh = gensym; 55 open $infh, $fn 56 or die "Could not open file $fn: $!\n"; 57 local $/; 58 return <$infh>; 59} 60 61# Read command line arguments 62 63my %options = ( 64 "help" => 0, 65 "man" => 0, 66 "sections" => [], 67 "full" => 0, 68 "out" => undef, 69 "verbose" => 0, 70 "modify" => 0, 71 "h1level" => 1, # section is equivalent to H1 72 "preamble" => [], 73 "postamble" => [], 74 ); 75# "prefile" is just like "preamble", but the argument 76# comes from the file named by the argument 77$options{"prefile"} = sub { shift; push @{$options{"preamble"}}, _get(shift) }; 78# the same between "postfile" and "postamble" 79$options{"postfile"} = sub { shift; push @{$options{"postamble"}}, _get(shift) }; 80 81GetOptions(\%options, 82 "help", 83 "man", 84 "verbose", 85 "full", 86 "sections=s@", 87 "out=s", 88 "modify", 89 "h1level=i", 90 "preamble=s@", 91 "postamble=s@", 92 "prefile=s", 93 "postfile=s" 94 ) || pod2usage(2); 95 96pod2usage(1) if ($options{help}); 97pod2usage(-verbose => 2) if ($options{man}); 98 99 100# Read all the files from the command line 101my @files = @ARGV; 102 103# Now find which ones are real pods and convert 104# directories to their contents. 105 106# Extract the pods from each arg since some of them might 107# be directories 108# This is not as efficient as using pod_find to search through 109# everything at once but it allows us to preserve the order 110# supplied by the user 111 112my @pods; 113foreach my $arg (@files) { 114 my %pods = pod_find($arg); 115 push(@pods, sort keys %pods); 116} 117 118# Abort if nothing to do 119if ($#pods == -1) { 120 warn "None of the supplied Pod files actually exist\n"; 121 exit; 122} 123 124# Only want to override the preamble and postamble if we have 125# been given values. 126my %User; 127$User{UserPreamble} = join("\n", @{$options{'preamble'}}) 128 if ($options{preamble} && @{$options{preamble}}); 129$User{UserPostamble} = join("\n", @{$options{'postamble'}}) 130 if ($options{postamble} && @{$options{postamble}}); 131 132 133 134# If $options{'out'} is set we are processing to a single output file 135my $multi_documents; 136if (exists $options{'out'} && defined $options{'out'}) { 137 $multi_documents = 0; 138} else { 139 $multi_documents = 1; 140} 141 142# If the output file is not specified it is assumed that 143# a single output file is required per input file using 144# a .tex extension rather than any existing extension 145 146if ($multi_documents) { 147 148 # Case where we just generate one input per output 149 150 foreach my $pod (@pods) { 151 152 if (-f $pod) { 153 154 my $output = $pod; 155 $output = basename($output, '.pm', '.pod','.pl') . '.tex'; 156 157 # Create a new parser object 158 my $parser = new Pod::LaTeX( 159 AddPreamble => $options{'full'}, 160 AddPostamble => $options{'full'}, 161 MakeIndex => $options{'full'}, 162 TableOfContents => $options{'full'}, 163 ReplaceNAMEwithSection => $options{'modify'}, 164 UniqueLabels => $options{'modify'}, 165 Head1Level => $options{'h1level'}, 166 LevelNoNum => $options{'h1level'} + 1, 167 %User, 168 ); 169 170 # Select sections if supplied 171 $parser->select(@{ $options{'sections'}}) 172 if @{$options{'sections'}}; 173 174 # Derive the input file from the output file 175 $parser->parse_from_file($pod, $output); 176 177 print "Written output to $output\n" if $options{'verbose'}; 178 179 } else { 180 warn "File $pod not found\n"; 181 } 182 183 } 184} else { 185 186 # Case where we want everything to be in a single document 187 188 # Need to open the output file ourselves 189 my $output = $options{'out'}; 190 $output .= '.tex' unless $output =~ /\.tex$/; 191 192 # Use auto-vivified file handle in perl 5.6 193 my $outfh = gensym; 194 open ($outfh, ">$output") || die "Could not open output file: $!\n"; 195 196 # Flag to indicate whether we have converted at least one file 197 # indicates how many files have been converted 198 my $converted = 0; 199 200 # Loop over the input files 201 foreach my $pod (@pods) { 202 203 if (-f $pod) { 204 205 warn "Converting $pod\n" if $options{'verbose'}; 206 207 # Open the file (need the handle) 208 # Use auto-vivified handle in perl 5.6 209 my $podfh = gensym; 210 open ($podfh, "<$pod") || die "Could not open pod file $pod: $!\n"; 211 212 # if this is the first file to be converted we may want to add 213 # a preamble (controlled by command line option) 214 my $preamble = 0; 215 $preamble = 1 if ($converted == 0 && $options{'full'}); 216 217 # if this is the last file to be converted may want to add 218 # a postamble (controlled by command line option) 219 # relies on a previous pass to check existence of all pods we 220 # are converting. 221 my $postamble = ( ($converted == $#pods && $options{'full'}) ? 1 : 0 ); 222 223 # Open parser object 224 # May want to start with a preamble for the first one and 225 # end with an index for the last 226 my $parser = new Pod::LaTeX( 227 MakeIndex => $options{'full'}, 228 TableOfContents => $preamble, 229 ReplaceNAMEwithSection => $options{'modify'}, 230 UniqueLabels => $options{'modify'}, 231 StartWithNewPage => $options{'full'}, 232 AddPreamble => $preamble, 233 AddPostamble => $postamble, 234 Head1Level => $options{'h1level'}, 235 LevelNoNum => $options{'h1level'} + 1, 236 %User 237 ); 238 239 # Store the file name for error messages 240 # This is a kluge that breaks the data hiding of the object 241 $parser->{_INFILE} = $pod; 242 243 # Select sections if supplied 244 $parser->select(@{ $options{'sections'}}) 245 if @{$options{'sections'}}; 246 247 # Parse it 248 $parser->parse_from_filehandle($podfh, $outfh); 249 250 # We have converted at least one file 251 $converted++; 252 253 } else { 254 warn "File $pod not found\n"; 255 } 256 257 } 258 259 # Should unlink the file if we didn't convert anything! 260 # dont check for return status of unlink 261 # since there is not a lot to be done if the unlink failed 262 # and the program does not rely upon it. 263 unlink "$output" unless $converted; 264 265 # If verbose 266 warn "Converted $converted files\n" if $options{'verbose'}; 267 268} 269 270exit; 271 272__END__ 273 274=head1 NAME 275 276pod2latex - convert pod documentation to latex format 277 278=head1 SYNOPSIS 279 280 pod2latex *.pm 281 282 pod2latex -out mytex.tex *.pod 283 284 pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir 285 286 pod2latex -prefile h.tex -postfile t.tex my.pod 287 288=head1 DESCRIPTION 289 290C<pod2latex> is a program to convert POD format documentation 291(L<perlpod>) into latex. It can process multiple input documents at a 292time and either generate a latex file per input document or a single 293combined output file. 294 295=head1 OPTIONS AND ARGUMENTS 296 297This section describes the supported command line options. Minimum 298matching is supported. 299 300=over 4 301 302=item B<-out> 303 304Name of the output file to be used. If there are multiple input pods 305it is assumed that the intention is to write all translated output 306into a single file. C<.tex> is appended if not present. If the 307argument is not supplied, a single document will be created for each 308input file. 309 310=item B<-full> 311 312Creates a complete C<latex> file that can be processed immediately 313(unless C<=for/=begin> directives are used that rely on extra packages). 314Table of contents and index generation commands are included in the 315wrapper C<latex> code. 316 317=item B<-sections> 318 319Specify pod sections to include (or remove if negated) in the 320translation. See L<Pod::Select/"SECTION SPECIFICATIONS"> for the 321format to use for I<section-spec>. This option may be given multiple 322times on the command line.This is identical to the similar option in 323the C<podselect()> command. 324 325=item B<-modify> 326 327This option causes the output C<latex> to be slightly 328modified from the input pod such that when a C<=head1 NAME> 329is encountered a section is created containing the actual 330pod name (rather than B<NAME>) and all subsequent C<=head1> 331directives are treated as subsections. This has the advantage 332that the description of a module will be in its own section 333which is helpful for including module descriptions in documentation. 334Also forces C<latex> label and index entries to be prefixed by the 335name of the module. 336 337=item B<-h1level> 338 339Specifies the C<latex> section that is equivalent to a C<H1> pod 340directive. This is an integer between 0 and 5 with 0 equivalent to a 341C<latex> chapter, 1 equivalent to a C<latex> section etc. The default 342is 1 (C<H1> equivalent to a latex section). 343 344=item B<-help> 345 346Print a brief help message and exit. 347 348=item B<-man> 349 350Print the manual page and exit. 351 352=item B<-verbose> 353 354Print information messages as each document is processed. 355 356=item B<-preamble> 357 358A user-supplied preamble for the LaTeX code. Multiple values 359are supported and appended in order separated by "\n". 360See B<-prefile> for reading the preamble from a file. 361 362=item B<-postamble> 363 364A user supplied postamble for the LaTeX code. Multiple values 365are supported and appended in order separated by "\n". 366See B<-postfile> for reading the postamble from a file. 367 368=item B<-prefile> 369 370A user-supplied preamble for the LaTeX code to be read from the 371named file. Multiple values are supported and appended in 372order. See B<-preamble>. 373 374=item B<-postfile> 375 376A user-supplied postamble for the LaTeX code to be read from the 377named file. Multiple values are supported and appended in 378order. See B<-postamble>. 379 380=back 381 382=head1 BUGS 383 384Known bugs are: 385 386=over 4 387 388=item * 389 390Cross references between documents are not resolved when multiple 391pod documents are converted into a single output C<latex> file. 392 393=item * 394 395Functions and variables are not automatically recognized 396and they will therefore not be marked up in any special way 397unless instructed by an explicit pod command. 398 399=back 400 401=head1 SEE ALSO 402 403L<Pod::LaTeX> 404 405=head1 AUTHOR 406 407Tim Jenness E<lt>tjenness@cpan.orgE<gt> 408 409This program is free software; you can redistribute it 410and/or modify it under the same terms as Perl itself. 411 412Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved. 413 414=cut 415 416!NO!SUBS! 417 418close OUT or die "Can't close $file: $!"; 419chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; 420exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; 421chdir $origdir; 422