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