-
Notifications
You must be signed in to change notification settings - Fork 14
/
pod2markdown
executable file
·125 lines (85 loc) · 2.81 KB
/
pod2markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
#!/usr/local/bin/perl
use 5.008;
use strict;
use warnings;
# PODNAME: pod2markdown
# ABSTRACT: Convert POD text to Markdown
use Pod::Markdown;
use Getopt::Long;
use Pod::Usage;
my %opts = (
# Since we're writing to a file the module needs to know that it has to do
# some kind of encoding. Default to UTF-8.
output_encoding => 'UTF-8',
);
GetOptions(\%opts, qw(
help|h
html_encode_chars|html-encode-chars=s
match_encoding|match-encoding|m
man_url_prefix|man-url-prefix=s
output_encoding|output-encoding|e=s
utf8|utf-8|u
)) or pod2usage(2);
pod2usage(1) if $opts{help};
# TODO: Test PERL_UNICODE and/or layers on the handle?
# Expand alias (-u is an alias for -e UTF-8).
$opts{output_encoding} = 'UTF-8' if delete $opts{utf8};
# TODO: Pod::Simple::parse_from_file(@ARGV[0,1]);
my $in_fh = get_handle(shift(@ARGV), '<', \*STDIN);
my $out_fh = get_handle(shift(@ARGV), '>', \*STDOUT);
# Undo any PERL_UNICODE effects.
# Pod::Simple expects to receive bytes, and we're going to return bytes.
binmode($_, ':bytes') for ($in_fh, $out_fh);
convert($in_fh, $out_fh);
sub convert {
my ($in_file, $out_file) = @_;
my $parser = Pod::Markdown->new(%opts);
$parser->output_fh($out_file);
$parser->parse_file($in_file);
}
sub get_handle {
my ($path, $op, $default) = @_;
(!defined($path) || $path eq '-') ? $default : do {
open(my $fh, $op, $path)
or die "Failed to open '$path': $!\n";
$fh;
};
}
=head1 SYNOPSIS
# parse STDIN, print to STDOUT
$ pod2markdown < POD_File > Markdown_File
# parse file, print to STDOUT
$ pod2markdown input.pod
# parse file, print to file
$ pod2markdown input.pod output.mkdn
# parse STDIN, print to file
$ pod2markdown - output.mkdn
=head1 DESCRIPTION
This program uses L<Pod::Markdown> to convert POD into Markdown sources.
UTF-8 is the default output encoding
if no encoding options are specified (see L</OPTIONS>).
It accepts two optional arguments:
=for :list
* input pod file (defaults to C<STDIN>)
* output markdown file (defaults to C<STDOUT>)
=head1 OPTIONS
=over
=for stopwords
html
=item --html-encode-chars
A list of characters to encode as HTML entities.
Pass a regexp character class, or C<1> to mean control chars, high-bit chars, and C<< <&>"' >>.
See L<Pod::Markdown/html_encode_chars> for more information.
=item --match-encoding (-m)
Use the same C<< =encoding >> as the input pod for the output file.
=item --man-url-prefix
Alters the man page urls that are created from C<< LE<lt>E<gt> >> codes.
The default is C<http://man.he.net/man>.
See L<Pod::Markdown/man_url_prefix> for more information.
=item --output-encoding (-e)
Specify the encoding for the output file.
=item --utf8 (-u)
Alias for C<< -e UTF-8 >>.
=back
=head1 SEE ALSO
This program is strongly based on C<pod2mdwn> from L<Module::Build::IkiWiki>.