Debian Codegraph @

bin/pom2

raw
1 #!/usr/bin/perl -w
2 #
3 # This program implements a simple translator to convert POD
4 # to HTML, Text, or back to POD again (e.g. for normalising a
5 # document). You can easily extend it to work with any other
6 # view modules you create which convert POD to different formats
7 # or in different styles.
8 #
9 # Written by Andy Wardley <[email protected]>. This is free software.
10 #
11 # Extended by Andrew Ford to check for any other installed viewers.
12
13 use Pod::POM;
14 use File::Basename;
15 use Getopt::Long;
16
17 my $PROGRAM = 'pom2';
18 my $program = basename($0);
19 my $format;
20 my $views = {
21 pod => 'Pod',
22 text => 'Text',
23 html => 'HTML',
24 };
25 my %options;
26
27 die usage() if grep(/^--?h(elp)?$/, @ARGV);
28
29 while (@ARGV and $ARGV[0] =~ /^--([^=]+)(=(.*))?$/) {
30 $options{$1} = $2 ? $3 : 1;
31 shift;
32 }
33
34 if ($program =~ /^$PROGRAM(.+)$/) {
35 $format = $1;
36 }
37 else {
38 $format = shift
39 || die usage('no output format specified');
40 }
41
42 while (@ARGV and $ARGV[0] =~ /^--([^=]+)(=(.*))?$/) {
43 $options{$1} = $2 ? $3 : 1;
44 shift;
45 }
46
47 my $file = shift
48 || die usage('no filename specified');
49
50 $format = lc $format;
51 my $view = $views->{ $format };
52
53 if (!$view) {
54 DIR:
55 foreach my $libdir (@INC) {
56 foreach (<$libdir/Pod/POM/View/*.pm>) {
57 (my $module = $_) =~ s{.*/([^/]+).pm$}{$1};
58 if (lc($module) eq $format) {
59 $view = $1;
60 last DIR;
61 }
62 else {
63 $views->{lc($module)} = $module;
64 }
65 }
66 }
67 $view || die usage("invalid format '$format', try one of: "
68 . join(', ', sort keys %$views));
69 }
70
71 $view = "Pod::POM::View::$view";
72 if (keys %options) {
73 eval "use $view";
74 $view = $view->new(%options);
75 }
76
77 Pod::POM->default_view($view)
78 || die "$Pod::POM::ERROR\n";
79
80 my $parser;
81 {
82 no warnings 'once'; # $Pod::POM::ERROR is only used once
83 $parser = Pod::POM->new( warn => 1 )
84 || die "$Pod::POM::ERROR\n";
85 }
86
87 my $pom = $parser->parse_file($file)
88 || die $parser->error(), "\n";
89
90 print $pom;
91
92
93 #------------------------------------------------------------------------
94
95 sub usage {
96 my $msg = shift || '';
97
98 if ($program =~ /^$PROGRAM$/) {
99 $program = "pom2 format";
100 }
101
102 return <<EOF;
103 ${msg}
104 usage: $program file
105 EOF
106 }
107
108 __END__
109
110 =head1 NAME
111
112 pom2 - convert POD to Text, HTML, etc., with Pod::POM
113
114 =head1 SYNOPSIS
115
116 pom2 text MyFile.pm > MyFile.txt
117 pom2 html MyFile.pm > MyFile.html
118 pom2 pod MyFile.pm > Myfile.pod
119
120 pom2 format [options] MyFile.pm > Myfile.xyz
121
122 =head1 DESCRIPTION
123
124 This script uses C<Pod::POM> to convert a Pod document into text,
125 HTML, back into Pod (e.g. to normalise a document to fix any
126 markup errors), or any other format for which you have a view
127 module.
128
129 If the viewer is not one of the viewers bundled with C<Pod::POM>, the script
130 searches for an installed C<Pod::POM::View> module that matches the
131 specified format. For example if you have C<Pod::POM::View::DocBook>
132 installed then you could say:
133
134 pod2 docbook MyFile.pm > MyFile.xml
135
136 If any options other than C<--help> are specified then they are passed
137 to the constructor method of the view class. For example:
138
139 pod2 docbook --root=chapter --titlecasing MyFile.pm > MyFile.xml
140
141 would convert the Pod document to a DocBook chapter document with the
142 titlecasing option enabled. Note that any string prefixed by "C<-->" is
143 taken as a valid option and passed to the constructor; if no value is
144 specified then a value of 1 is passed in.
145
146
147 =head1 AUTHOR
148
149 Andy Wardley E<lt>[email protected]<gt>
150
151 extended by Andrew Ford E<lt>[email protected]<gt>
152
153 =head1 VERSION
154
155 This is version 0.3 of pom2.
156
157 =head1 COPYRIGHT
158
159 Copyright (C) 2000, 2001 Andy Wardley. All Rights Reserved.
160
161 Copyright (C) 2009 Andrew Ford. All Rights Reserved.
162
163 This module is free software; you can redistribute it and/or
164 modify it under the same terms as Perl itself.
165
166 =head1 SEE ALSO
167
168 For further information please see L<Pod::POM>.
169