Commit | Line | Data |
---|---|---|
4633a7c4 LW |
1 | #!/usr/local/bin/perl |
2 | ||
3 | use Config; | |
4 | use File::Basename qw(&basename &dirname); | |
3b5ca523 | 5 | use Cwd; |
4633a7c4 LW |
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 | ||
3b5ca523 GS |
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'); | |
774d564b | 19 | $file .= '.com' if $^O eq 'VMS'; |
4633a7c4 LW |
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!"; | |
5f05dabc | 29 | $Config{startperl} |
30 | eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' | |
31 | if \$running_under_some_shell; | |
5d94fbed AD |
32 | !GROK!THIS! |
33 | ||
4633a7c4 LW |
34 | # In the following, perl variables are not expanded during extraction. |
35 | ||
36 | print OUT <<'!NO!SUBS!'; | |
748a9306 | 37 | |
076c2fc0 GS |
38 | # pod2latex conversion program |
39 | ||
1826411a | 40 | use strict; |
076c2fc0 GS |
41 | use Pod::LaTeX; |
42 | use Pod::Find qw/ pod_find /; | |
43 | use Pod::Usage; | |
44 | use Getopt::Long; | |
45 | use File::Basename; | |
72e5dea6 RGS |
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 | } | |
1826411a | 60 | |
076c2fc0 GS |
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, | |
1826411a | 71 | "h1level" => 1, # section is equivalent to H1 |
72e5dea6 RGS |
72 | "preamble" => [], |
73 | "postamble" => [], | |
076c2fc0 | 74 | ); |
72e5dea6 RGS |
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) }; | |
076c2fc0 GS |
80 | |
81 | GetOptions(\%options, | |
82 | "help", | |
83 | "man", | |
84 | "verbose", | |
85 | "full", | |
86 | "sections=s@", | |
87 | "out=s", | |
88 | "modify", | |
1826411a | 89 | "h1level=i", |
72e5dea6 RGS |
90 | "preamble=s@", |
91 | "postamble=s@", | |
92 | "prefile=s", | |
93 | "postfile=s" | |
076c2fc0 GS |
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 | } | |
8c634b6e | 117 | |
076c2fc0 GS |
118 | # Abort if nothing to do |
119 | if ($#pods == -1) { | |
120 | warn "None of the supplied Pod files actually exist\n"; | |
121 | exit; | |
122 | } | |
748a9306 | 123 | |
72e5dea6 RGS |
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 | ||
748a9306 LW |
132 | |
133 | ||
076c2fc0 GS |
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'; | |
748a9306 | 156 | |
076c2fc0 GS |
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'}, | |
1826411a TJ |
165 | Head1Level => $options{'h1level'}, |
166 | LevelNoNum => $options{'h1level'} + 1, | |
72e5dea6 | 167 | %User, |
076c2fc0 | 168 | ); |
748a9306 | 169 | |
076c2fc0 GS |
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"; | |
748a9306 | 181 | } |
076c2fc0 GS |
182 | |
183 | } | |
184 | } else { | |
72e5dea6 | 185 | |
076c2fc0 GS |
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 | |
076c2fc0 GS |
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) | |
1826411a TJ |
214 | my $preamble = 0; |
215 | $preamble = 1 if ($converted == 0 && $options{'full'}); | |
076c2fc0 GS |
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, | |
1826411a TJ |
234 | Head1Level => $options{'h1level'}, |
235 | LevelNoNum => $options{'h1level'} + 1, | |
72e5dea6 | 236 | %User |
076c2fc0 GS |
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"; | |
748a9306 | 255 | } |
748a9306 | 256 | |
076c2fc0 | 257 | } |
748a9306 | 258 | |
076c2fc0 GS |
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; | |
748a9306 | 264 | |
076c2fc0 GS |
265 | # If verbose |
266 | warn "Converted $converted files\n" if $options{'verbose'}; | |
748a9306 | 267 | |
748a9306 LW |
268 | } |
269 | ||
076c2fc0 | 270 | exit; |
748a9306 | 271 | |
076c2fc0 | 272 | __END__ |
748a9306 | 273 | |
076c2fc0 | 274 | =head1 NAME |
748a9306 | 275 | |
076c2fc0 | 276 | pod2latex - convert pod documentation to latex format |
748a9306 | 277 | |
076c2fc0 | 278 | =head1 SYNOPSIS |
748a9306 | 279 | |
076c2fc0 | 280 | pod2latex *.pm |
748a9306 | 281 | |
076c2fc0 | 282 | pod2latex -out mytex.tex *.pod |
748a9306 | 283 | |
076c2fc0 | 284 | pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir |
748a9306 | 285 | |
72e5dea6 RGS |
286 | pod2latex -prefile h.tex -postfile t.tex my.pod |
287 | ||
076c2fc0 | 288 | =head1 DESCRIPTION |
748a9306 | 289 | |
076c2fc0 GS |
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 | ||
a6d05634 | 297 | This section describes the supported command line options. Minimum |
076c2fc0 GS |
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 | ||
1826411a TJ |
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 | ||
076c2fc0 GS |
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 | ||
72e5dea6 RGS |
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 | ||
076c2fc0 GS |
380 | =back |
381 | ||
382 | =head1 BUGS | |
383 | ||
384 | Known bugs are: | |
385 | ||
386 | =over 4 | |
387 | ||
72e5dea6 | 388 | =item * |
076c2fc0 GS |
389 | |
390 | Cross references between documents are not resolved when multiple | |
391 | pod documents are converted into a single output C<latex> file. | |
392 | ||
72e5dea6 | 393 | =item * |
076c2fc0 | 394 | |
72e5dea6 | 395 | Functions and variables are not automatically recognized |
076c2fc0 GS |
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 | ||
72e5dea6 | 407 | Tim Jenness E<lt>tjenness@cpan.orgE<gt> |
076c2fc0 GS |
408 | |
409 | This program is free software; you can redistribute it | |
410 | and/or modify it under the same terms as Perl itself. | |
411 | ||
72e5dea6 | 412 | Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved. |
076c2fc0 GS |
413 | |
414 | =cut | |
748a9306 | 415 | |
5d94fbed | 416 | !NO!SUBS! |
4633a7c4 LW |
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 ':'; | |
3b5ca523 | 421 | chdir $origdir; |