| 1 |
#!/usr/bin/env perl |
| 2 |
|
| 3 |
use v5.10.1; |
| 4 |
|
| 5 |
use strict; |
| 6 |
use warnings; |
| 7 |
|
| 8 |
use File::Copy qw/ copy /; |
| 9 |
use Getopt::Long::Descriptive; |
| 10 |
use IO::Handle; |
| 11 |
use Pod::Readme; |
| 12 |
|
| 13 |
our $VERSION = 'v1.2.3'; |
| 14 |
|
| 15 |
=head1 NAME |
| 16 |
|
| 17 |
pod2readme - Intelligently generate a README file from POD |
| 18 |
|
| 19 |
=head1 USAGE |
| 20 |
|
| 21 |
pod2readme [-cfho] [long options...] input-file [output-file] [target] |
| 22 |
|
| 23 |
Intelligently generate a README file from POD |
| 24 |
|
| 25 |
-t --target target type (default: 'readme') |
| 26 |
-f --format output format (default: 'text') |
| 27 |
-b --backup backup output file |
| 28 |
-o --output output filename (default based on target) |
| 29 |
-c --stdout output to stdout (console) |
| 30 |
-F --force only update if files are changed |
| 31 |
-h --help print usage and exit |
| 32 |
|
| 33 |
=head1 SYNOPSIS |
| 34 |
|
| 35 |
pod2readme -f markdown lib/MyApp.pm |
| 36 |
|
| 37 |
=head1 DESCRIPTION |
| 38 |
|
| 39 |
This utility will use L<Pod::Readme> to extract a F<README> file from |
| 40 |
a POD document. |
| 41 |
|
| 42 |
It works by extracting and filtering the POD, and then calling the |
| 43 |
appropriate filter program to convert the POD to another format. |
| 44 |
|
| 45 |
=head1 OPTIONS |
| 46 |
|
| 47 |
=head2 C<--backup> |
| 48 |
|
| 49 |
By default, C<pod2readme> will back up the output file. To disable |
| 50 |
this, use the C<--no-backup> option. |
| 51 |
|
| 52 |
=head2 C<--output> |
| 53 |
|
| 54 |
Specifies the name of the output file. If omitted, it will use the |
| 55 |
second command line argument, or default to the C<--target> plus the |
| 56 |
corresponding extension of the C<--format>. |
| 57 |
|
| 58 |
For all intents, the default is F<README>. |
| 59 |
|
| 60 |
If a format other than "text" is chosen, then the appropriate |
| 61 |
extension will be added, e.g. for "markdown", the default output file |
| 62 |
is F<README.md>. |
| 63 |
|
| 64 |
=head2 C<--target> |
| 65 |
|
| 66 |
The target of the filter, which defaults to "readme". |
| 67 |
|
| 68 |
=head2 C<--format> |
| 69 |
|
| 70 |
The output format, which defaults to "text". |
| 71 |
|
| 72 |
Other supposed formats are "github", "html", "latex", "man", |
| 73 |
"markdown", "pod", "rtf", and "xhtml". You can also use "gfm" |
| 74 |
instead of "github". Similary you can use "md" for "markdown". |
| 75 |
|
| 76 |
=head2 C<--stdout> |
| 77 |
|
| 78 |
If enabled, it will output to the console instead of C<--output>. |
| 79 |
|
| 80 |
=head2 C<--force> |
| 81 |
|
| 82 |
By default, the F<README> will be generated if the source files have |
| 83 |
been changed. Using C<--force> will force the file to be updated. |
| 84 |
|
| 85 |
Note: POD format files will always be updated. |
| 86 |
|
| 87 |
=head2 C<--help> |
| 88 |
|
| 89 |
Prints the usage and exits. |
| 90 |
|
| 91 |
=head1 SEE ALSO |
| 92 |
|
| 93 |
L<pod2text>, L<pod2markdown>. |
| 94 |
|
| 95 |
=cut |
| 96 |
|
| 97 |
my %FORMATS = ( |
| 98 |
'gfm' => { class => 'Pod::Markdown::Github' }, |
| 99 |
'github' => { class => 'Pod::Markdown::Github' }, |
| 100 |
'html' => { class => 'Pod::Simple::HTML', }, |
| 101 |
'latex' => { class => 'Pod::Simple::LaTeX' }, |
| 102 |
'man' => { class => 'Pod::Man' }, |
| 103 |
'markdown' => { class => 'Pod::Markdown' }, |
| 104 |
'md' => { class => 'Pod::Markdown' }, |
| 105 |
'pod' => { class => undef }, |
| 106 |
'rtf' => { class => 'Pod::Simple::RTF' }, |
| 107 |
'text' => { class => 'Pod::Simple::Text' }, |
| 108 |
'xhtml' => { class => 'Pod::Simple::XHTML' }, |
| 109 |
); |
| 110 |
|
| 111 |
sub validate_format { |
| 112 |
my $value = shift; |
| 113 |
if ( exists $FORMATS{$value} ) { |
| 114 |
return $value; |
| 115 |
} |
| 116 |
else { |
| 117 |
die "Invalid format: '${value}'\n"; |
| 118 |
} |
| 119 |
} |
| 120 |
|
| 121 |
my ( $opt, $usage ) = describe_options( |
| 122 |
'%c %o input-file [output-file] [target]', |
| 123 |
[], |
| 124 |
['Intelligently generate a README file from POD'], |
| 125 |
[], |
| 126 |
[ 'target|t=s' => "target type (default: 'readme')" ], |
| 127 |
[ |
| 128 |
'format|f=s' => "output format (default: 'text')", |
| 129 |
{ |
| 130 |
default => 'text', |
| 131 |
callbacks => { format => \&validate_format }, |
| 132 |
} |
| 133 |
], |
| 134 |
[ 'backup|b!' => "backup output file", { default => 1 } ], |
| 135 |
[ 'output|o' => "output filename (default based on target)" ], |
| 136 |
[ 'stdout|c' => "output to stdout (console)" ], |
| 137 |
[ 'force|F!' => "only update if files are changed" ], |
| 138 |
[ 'help|h' => "print usage and exit" ], |
| 139 |
); |
| 140 |
|
| 141 |
die $usage if $opt->help; |
| 142 |
|
| 143 |
my %args = ( force => $opt->force ); |
| 144 |
|
| 145 |
if ( my $input = shift @ARGV ) { |
| 146 |
$args{input_file} = $input; |
| 147 |
} |
| 148 |
|
| 149 |
my $format = $FORMATS{ $opt->format }; |
| 150 |
unless ($format) { |
| 151 |
say sprintf( "Unknown format: '\%s'", $opt->format ); |
| 152 |
die $usage; |
| 153 |
} |
| 154 |
|
| 155 |
my $output = $opt->output || shift @ARGV; |
| 156 |
my $target = $opt->target || shift @ARGV || 'readme'; |
| 157 |
|
| 158 |
$args{target} = $target; |
| 159 |
|
| 160 |
if ( my $class = $format->{class} ) { |
| 161 |
$args{translation_class} = $class; |
| 162 |
} |
| 163 |
|
| 164 |
if ( $opt->stdout ) { |
| 165 |
my $fh = IO::Handle->new; |
| 166 |
if ( $fh->fdopen( fileno(STDOUT), 'w' ) ) { |
| 167 |
$args{translate_to_fh} = $fh; |
| 168 |
} |
| 169 |
else { |
| 170 |
die "Cannot get a filehandle for STDOUT"; |
| 171 |
} |
| 172 |
} |
| 173 |
else { |
| 174 |
$args{translate_to_file} = $output if $output; |
| 175 |
} |
| 176 |
|
| 177 |
my $pr = Pod::Readme->new(%args); |
| 178 |
|
| 179 |
$output ||= $pr->translate_to_file; |
| 180 |
|
| 181 |
if ( $opt->backup && $output && -e $output ) { |
| 182 |
copy( $output, $output . '.bak' ); |
| 183 |
} |
| 184 |
|
| 185 |
$pr->run(); |