| 1 | #!/usr/local/bin/perl |
| 2 | |
| 3 | use Config; |
| 4 | use File::Basename qw(&basename &dirname); |
| 5 | use 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; |
| 17 | chdir dirname($0); |
| 18 | $file = basename($0, '.PL'); |
| 19 | $file .= '.com' if $^O eq 'VMS'; |
| 20 | |
| 21 | open OUT,">$file" or die "Can't create $file: $!"; |
| 22 | |
| 23 | print "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 | |
| 28 | print 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 | |
| 36 | print OUT <<'!NO!SUBS!'; |
| 37 | |
| 38 | # pod2latex conversion program |
| 39 | |
| 40 | use strict; |
| 41 | use Pod::LaTeX; |
| 42 | use Pod::Find qw/ pod_find /; |
| 43 | use Pod::Usage; |
| 44 | use Getopt::Long; |
| 45 | use File::Basename; |
| 46 | use Symbol; |
| 47 | |
| 48 | my $VERSION = "1.01"; |
| 49 | |
| 50 | # return the entire contents of a text file |
| 51 | # whose name is given as argument |
| 52 | sub _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 | |
| 63 | my %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 | |
| 81 | GetOptions(\%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 | |
| 96 | pod2usage(1) if ($options{help}); |
| 97 | pod2usage(-verbose => 2) if ($options{man}); |
| 98 | |
| 99 | |
| 100 | # Read all the files from the command line |
| 101 | my @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 | |
| 112 | my @pods; |
| 113 | foreach my $arg (@files) { |
| 114 | my %pods = pod_find($arg); |
| 115 | push(@pods, sort keys %pods); |
| 116 | } |
| 117 | |
| 118 | # Abort if nothing to do |
| 119 | if ($#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. |
| 126 | my %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 |
| 135 | my $multi_documents; |
| 136 | if (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 exisiting extension |
| 145 | |
| 146 | if ($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 | |
| 270 | exit; |
| 271 | |
| 272 | __END__ |
| 273 | |
| 274 | =head1 NAME |
| 275 | |
| 276 | pod2latex - 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 | |
| 290 | C<pod2latex> is a program to convert POD format documentation |
| 291 | (L<perlpod>) into latex. It can process multiple input documents at a |
| 292 | time and either generate a latex file per input document or a single |
| 293 | combined output file. |
| 294 | |
| 295 | =head1 OPTIONS AND ARGUMENTS |
| 296 | |
| 297 | This section describes the supported command line options. Minimum |
| 298 | matching is supported. |
| 299 | |
| 300 | =over 4 |
| 301 | |
| 302 | =item B<-out> |
| 303 | |
| 304 | Name of the output file to be used. If there are multiple input pods |
| 305 | it is assumed that the intention is to write all translated output |
| 306 | into a single file. C<.tex> is appended if not present. If the |
| 307 | argument is not supplied, a single document will be created for each |
| 308 | input file. |
| 309 | |
| 310 | =item B<-full> |
| 311 | |
| 312 | Creates a complete C<latex> file that can be processed immediately |
| 313 | (unless C<=for/=begin> directives are used that rely on extra packages). |
| 314 | Table of contents and index generation commands are included in the |
| 315 | wrapper C<latex> code. |
| 316 | |
| 317 | =item B<-sections> |
| 318 | |
| 319 | Specify pod sections to include (or remove if negated) in the |
| 320 | translation. See L<Pod::Select/"SECTION SPECIFICATIONS"> for the |
| 321 | format to use for I<section-spec>. This option may be given multiple |
| 322 | times on the command line.This is identical to the similar option in |
| 323 | the C<podselect()> command. |
| 324 | |
| 325 | =item B<-modify> |
| 326 | |
| 327 | This option causes the output C<latex> to be slightly |
| 328 | modified from the input pod such that when a C<=head1 NAME> |
| 329 | is encountered a section is created containing the actual |
| 330 | pod name (rather than B<NAME>) and all subsequent C<=head1> |
| 331 | directives are treated as subsections. This has the advantage |
| 332 | that the description of a module will be in its own section |
| 333 | which is helpful for including module descriptions in documentation. |
| 334 | Also forces C<latex> label and index entries to be prefixed by the |
| 335 | name of the module. |
| 336 | |
| 337 | =item B<-h1level> |
| 338 | |
| 339 | Specifies the C<latex> section that is equivalent to a C<H1> pod |
| 340 | directive. This is an integer between 0 and 5 with 0 equivalent to a |
| 341 | C<latex> chapter, 1 equivalent to a C<latex> section etc. The default |
| 342 | is 1 (C<H1> equivalent to a latex section). |
| 343 | |
| 344 | =item B<-help> |
| 345 | |
| 346 | Print a brief help message and exit. |
| 347 | |
| 348 | =item B<-man> |
| 349 | |
| 350 | Print the manual page and exit. |
| 351 | |
| 352 | =item B<-verbose> |
| 353 | |
| 354 | Print information messages as each document is processed. |
| 355 | |
| 356 | =item B<-preamble> |
| 357 | |
| 358 | A user-supplied preamble for the LaTeX code. Multiple values |
| 359 | are supported and appended in order separated by "\n". |
| 360 | See B<-prefile> for reading the preamble from a file. |
| 361 | |
| 362 | =item B<-postamble> |
| 363 | |
| 364 | A user supplied postamble for the LaTeX code. Multiple values |
| 365 | are supported and appended in order separated by "\n". |
| 366 | See B<-postfile> for reading the postamble from a file. |
| 367 | |
| 368 | =item B<-prefile> |
| 369 | |
| 370 | A user-supplied preamble for the LaTeX code to be read from the |
| 371 | named file. Multiple values are supported and appended in |
| 372 | order. See B<-preamble>. |
| 373 | |
| 374 | =item B<-postfile> |
| 375 | |
| 376 | A user-supplied postamble for the LaTeX code to be read from the |
| 377 | named file. Multiple values are supported and appended in |
| 378 | order. See B<-postamble>. |
| 379 | |
| 380 | =back |
| 381 | |
| 382 | =head1 BUGS |
| 383 | |
| 384 | Known bugs are: |
| 385 | |
| 386 | =over 4 |
| 387 | |
| 388 | =item * |
| 389 | |
| 390 | Cross references between documents are not resolved when multiple |
| 391 | pod documents are converted into a single output C<latex> file. |
| 392 | |
| 393 | =item * |
| 394 | |
| 395 | Functions and variables are not automatically recognized |
| 396 | and they will therefore not be marked up in any special way |
| 397 | unless instructed by an explicit pod command. |
| 398 | |
| 399 | =back |
| 400 | |
| 401 | =head1 SEE ALSO |
| 402 | |
| 403 | L<Pod::LaTeX> |
| 404 | |
| 405 | =head1 AUTHOR |
| 406 | |
| 407 | Tim Jenness E<lt>tjenness@cpan.orgE<gt> |
| 408 | |
| 409 | This program is free software; you can redistribute it |
| 410 | and/or modify it under the same terms as Perl itself. |
| 411 | |
| 412 | Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved. |
| 413 | |
| 414 | =cut |
| 415 | |
| 416 | !NO!SUBS! |
| 417 | |
| 418 | close OUT or die "Can't close $file: $!"; |
| 419 | chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; |
| 420 | exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; |
| 421 | chdir $origdir; |