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