Updated git wrapper exe
[msysgit.git] / bin / pod2latex
blob9e21d2ad9e6d47ef9a213b87e6081a2c09e9fbe1
1 #!/usr/bin/perl
2 eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
3 if $running_under_some_shell;
5 # pod2latex conversion program
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 use Symbol;
15 my $VERSION = "1.01";
17 # return the entire contents of a text file
18 # whose name is given as argument
19 sub _get {
20 my $fn = shift;
21 my $infh = gensym;
22 open $infh, $fn
23 or die "Could not open file $fn: $!\n";
24 local $/;
25 return <$infh>;
28 # Read command line arguments
30 my %options = (
31 "help" => 0,
32 "man" => 0,
33 "sections" => [],
34 "full" => 0,
35 "out" => undef,
36 "verbose" => 0,
37 "modify" => 0,
38 "h1level" => 1, # section is equivalent to H1
39 "preamble" => [],
40 "postamble" => [],
42 # "prefile" is just like "preamble", but the argument
43 # comes from the file named by the argument
44 $options{"prefile"} = sub { shift; push @{$options{"preamble"}}, _get(shift) };
45 # the same between "postfile" and "postamble"
46 $options{"postfile"} = sub { shift; push @{$options{"postamble"}}, _get(shift) };
48 GetOptions(\%options,
49 "help",
50 "man",
51 "verbose",
52 "full",
53 "sections=s@",
54 "out=s",
55 "modify",
56 "h1level=i",
57 "preamble=s@",
58 "postamble=s@",
59 "prefile=s",
60 "postfile=s"
61 ) || pod2usage(2);
63 pod2usage(1) if ($options{help});
64 pod2usage(-verbose => 2) if ($options{man});
67 # Read all the files from the command line
68 my @files = @ARGV;
70 # Now find which ones are real pods and convert
71 # directories to their contents.
73 # Extract the pods from each arg since some of them might
74 # be directories
75 # This is not as efficient as using pod_find to search through
76 # everything at once but it allows us to preserve the order
77 # supplied by the user
79 my @pods;
80 foreach my $arg (@files) {
81 my %pods = pod_find($arg);
82 push(@pods, sort keys %pods);
85 # Abort if nothing to do
86 if ($#pods == -1) {
87 warn "None of the supplied Pod files actually exist\n";
88 exit;
91 # Only want to override the preamble and postamble if we have
92 # been given values.
93 my %User;
94 $User{UserPreamble} = join("\n", @{$options{'preamble'}})
95 if ($options{preamble} && @{$options{preamble}});
96 $User{UserPostamble} = join("\n", @{$options{'postamble'}})
97 if ($options{postamble} && @{$options{postamble}});
101 # If $options{'out'} is set we are processing to a single output file
102 my $multi_documents;
103 if (exists $options{'out'} && defined $options{'out'}) {
104 $multi_documents = 0;
105 } else {
106 $multi_documents = 1;
109 # If the output file is not specified it is assumed that
110 # a single output file is required per input file using
111 # a .tex extension rather than any exisiting extension
113 if ($multi_documents) {
115 # Case where we just generate one input per output
117 foreach my $pod (@pods) {
119 if (-f $pod) {
121 my $output = $pod;
122 $output = basename($output, '.pm', '.pod','.pl') . '.tex';
124 # Create a new parser object
125 my $parser = new Pod::LaTeX(
126 AddPreamble => $options{'full'},
127 AddPostamble => $options{'full'},
128 MakeIndex => $options{'full'},
129 TableOfContents => $options{'full'},
130 ReplaceNAMEwithSection => $options{'modify'},
131 UniqueLabels => $options{'modify'},
132 Head1Level => $options{'h1level'},
133 LevelNoNum => $options{'h1level'} + 1,
134 %User,
137 # Select sections if supplied
138 $parser->select(@{ $options{'sections'}})
139 if @{$options{'sections'}};
141 # Derive the input file from the output file
142 $parser->parse_from_file($pod, $output);
144 print "Written output to $output\n" if $options{'verbose'};
146 } else {
147 warn "File $pod not found\n";
151 } else {
153 # Case where we want everything to be in a single document
155 # Need to open the output file ourselves
156 my $output = $options{'out'};
157 $output .= '.tex' unless $output =~ /\.tex$/;
159 # Use auto-vivified file handle in perl 5.6
160 my $outfh = gensym;
161 open ($outfh, ">$output") || die "Could not open output file: $!\n";
163 # Flag to indicate whether we have converted at least one file
164 # indicates how many files have been converted
165 my $converted = 0;
167 # Loop over the input files
168 foreach my $pod (@pods) {
170 if (-f $pod) {
172 warn "Converting $pod\n" if $options{'verbose'};
174 # Open the file (need the handle)
175 # Use auto-vivified handle in perl 5.6
176 my $podfh = gensym;
177 open ($podfh, "<$pod") || die "Could not open pod file $pod: $!\n";
179 # if this is the first file to be converted we may want to add
180 # a preamble (controlled by command line option)
181 my $preamble = 0;
182 $preamble = 1 if ($converted == 0 && $options{'full'});
184 # if this is the last file to be converted may want to add
185 # a postamble (controlled by command line option)
186 # relies on a previous pass to check existence of all pods we
187 # are converting.
188 my $postamble = ( ($converted == $#pods && $options{'full'}) ? 1 : 0 );
190 # Open parser object
191 # May want to start with a preamble for the first one and
192 # end with an index for the last
193 my $parser = new Pod::LaTeX(
194 MakeIndex => $options{'full'},
195 TableOfContents => $preamble,
196 ReplaceNAMEwithSection => $options{'modify'},
197 UniqueLabels => $options{'modify'},
198 StartWithNewPage => $options{'full'},
199 AddPreamble => $preamble,
200 AddPostamble => $postamble,
201 Head1Level => $options{'h1level'},
202 LevelNoNum => $options{'h1level'} + 1,
203 %User
206 # Store the file name for error messages
207 # This is a kluge that breaks the data hiding of the object
208 $parser->{_INFILE} = $pod;
210 # Select sections if supplied
211 $parser->select(@{ $options{'sections'}})
212 if @{$options{'sections'}};
214 # Parse it
215 $parser->parse_from_filehandle($podfh, $outfh);
217 # We have converted at least one file
218 $converted++;
220 } else {
221 warn "File $pod not found\n";
226 # Should unlink the file if we didn't convert anything!
227 # dont check for return status of unlink
228 # since there is not a lot to be done if the unlink failed
229 # and the program does not rely upon it.
230 unlink "$output" unless $converted;
232 # If verbose
233 warn "Converted $converted files\n" if $options{'verbose'};
237 exit;
239 __END__
241 =head1 NAME
243 pod2latex - convert pod documentation to latex format
245 =head1 SYNOPSIS
247 pod2latex *.pm
249 pod2latex -out mytex.tex *.pod
251 pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir
253 pod2latex -prefile h.tex -postfile t.tex my.pod
255 =head1 DESCRIPTION
257 C<pod2latex> is a program to convert POD format documentation
258 (L<perlpod>) into latex. It can process multiple input documents at a
259 time and either generate a latex file per input document or a single
260 combined output file.
262 =head1 OPTIONS AND ARGUMENTS
264 This section describes the supported command line options. Minimum
265 matching is supported.
267 =over 4
269 =item B<-out>
271 Name of the output file to be used. If there are multiple input pods
272 it is assumed that the intention is to write all translated output
273 into a single file. C<.tex> is appended if not present. If the
274 argument is not supplied, a single document will be created for each
275 input file.
277 =item B<-full>
279 Creates a complete C<latex> file that can be processed immediately
280 (unless C<=for/=begin> directives are used that rely on extra packages).
281 Table of contents and index generation commands are included in the
282 wrapper C<latex> code.
284 =item B<-sections>
286 Specify pod sections to include (or remove if negated) in the
287 translation. See L<Pod::Select/"SECTION SPECIFICATIONS"> for the
288 format to use for I<section-spec>. This option may be given multiple
289 times on the command line.This is identical to the similar option in
290 the C<podselect()> command.
292 =item B<-modify>
294 This option causes the output C<latex> to be slightly
295 modified from the input pod such that when a C<=head1 NAME>
296 is encountered a section is created containing the actual
297 pod name (rather than B<NAME>) and all subsequent C<=head1>
298 directives are treated as subsections. This has the advantage
299 that the description of a module will be in its own section
300 which is helpful for including module descriptions in documentation.
301 Also forces C<latex> label and index entries to be prefixed by the
302 name of the module.
304 =item B<-h1level>
306 Specifies the C<latex> section that is equivalent to a C<H1> pod
307 directive. This is an integer between 0 and 5 with 0 equivalent to a
308 C<latex> chapter, 1 equivalent to a C<latex> section etc. The default
309 is 1 (C<H1> equivalent to a latex section).
311 =item B<-help>
313 Print a brief help message and exit.
315 =item B<-man>
317 Print the manual page and exit.
319 =item B<-verbose>
321 Print information messages as each document is processed.
323 =item B<-preamble>
325 A user-supplied preamble for the LaTeX code. Multiple values
326 are supported and appended in order separated by "\n".
327 See B<-prefile> for reading the preamble from a file.
329 =item B<-postamble>
331 A user supplied postamble for the LaTeX code. Multiple values
332 are supported and appended in order separated by "\n".
333 See B<-postfile> for reading the postamble from a file.
335 =item B<-prefile>
337 A user-supplied preamble for the LaTeX code to be read from the
338 named file. Multiple values are supported and appended in
339 order. See B<-preamble>.
341 =item B<-postfile>
343 A user-supplied postamble for the LaTeX code to be read from the
344 named file. Multiple values are supported and appended in
345 order. See B<-postamble>.
347 =back
349 =head1 BUGS
351 Known bugs are:
353 =over 4
355 =item *
357 Cross references between documents are not resolved when multiple
358 pod documents are converted into a single output C<latex> file.
360 =item *
362 Functions and variables are not automatically recognized
363 and they will therefore not be marked up in any special way
364 unless instructed by an explicit pod command.
366 =back
368 =head1 SEE ALSO
370 L<Pod::LaTeX>
372 =head1 AUTHOR
374 Tim Jenness E<lt>tjenness@cpan.orgE<gt>
376 This program is free software; you can redistribute it
377 and/or modify it under the same terms as Perl itself.
379 Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved.
381 =cut