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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
package Pod::Pandoc;
use strict;
use warnings;
require 5.010;
our $VERSION = '0.5.0';
use Pod::Simple::Pandoc;
use Pod::Pandoc::Modules;
use App::pod2pandoc;
1;
__END__
=head1 NAME
Pod::Pandoc - process Plain Old Documentation format with Pandoc
=begin markdown
# STATUS
[](https://travis-ci.org/nichtich/Pod-Pandoc)
[](https://ci.appveyor.com/project/nichtich/pod-pandoc)
[](https://coveralls.io/r/nichtich/Pod-Pandoc)
[](http://cpants.cpanauthors.org/dist/Pod-Pandoc)
[](https://codeclimate.com/github/nichtich/Pod-Pandoc)
[](http://pod-pandoc.readthedocs.io/?badge=latest)
=end markdown
=head1 DESCRIPTION
The Plain Old Documentation format (Pod) is a markup language used to document
Perl code (see L<perlpod> for reference). Several Perl modules exist to process
and convert Pod into other formats.
Pod::Pandoc is an attempt to unify and extend Pod converting based on the
L<Pandoc|http://pandoc.org/> document converter. Pandoc supports more document
formats in a more detailled and uniform way than any set of Perl modules will
ever do. For this reason Pod::Pandoc provides methods to convert Pod to the
Pandoc document model for further processing with Pandoc.
=head1 OUTLINE
=over
=item
L<pod2pandoc> is a command line script to convert Pod to any format supported
by Pandoc.
=item
L<App::pod2pandoc> provides functionality of L<pod2pandoc> to be used in Perl code.
=item
L<Pod::Simple::Pandoc> converts Pod to the abstract document model of Pandoc.
=item
L<Pod::Pandoc::Modules> manages a set of Pod documents of Perl modules.
=back
=head1 REQUIREMENTS
Installation of this module does not require Pandoc but it is needed to make
actual use of it. See L<http://pandoc.org/installing.html> for installation.
=head1 USAGE EXAMPLES
=head2 Replace L<pod2html>
# pod2html --infile=input.pm --css=style.css --title=TITLE > output.html
pod2pandoc input.pm --css=style.css --toc --name -o output.html
Pandoc option C<--toc> corresponds to pod2html option C<--index> and is
disabled by default. pod2pandoc adds title and subtitle from NAME section.
=head2 Replace L<pod2markdown>
# pod2markdown input.pod
pod2pandoc input.pod -t markdown
# pod2markdown input.pod output.md
pod2pandoc input.pod -o output.md
=head2 GitHub wiki
The L<GitHub wiki of this project|https://github.com/nichtich/Pod-Pandoc/wiki>
is automatically populated with its module documentation. Wiki pages
are created with L<pod2pandoc> as following (see script C<update-wiki.sh>):
pod2pandoc lib/ script/ wiki/ --ext md --index Home --wiki -t markdown_github
=head2 Sphinx and Read The Docs
The L<Sphinx documentation generator|https://sphinx-doc.org/> recommends
documents in reStructureText format. It further requires a configuration file
C<conf.py> and some links need to be adjusted because Pandoc does not support
wikilinks in rst output format (see script C<update-docs.sh>:
pod2pandoc lib/ script/ docs/ --ext rst --wiki -t rst --standalone
perl -pi -e 's!`([^`]+) <([^>]+)>`__!-e "docs/$2.rst" ? ":doc:`$1 <$2>`" : "`$1 <$2>`__"!e' docs/*.rst
make -C docs html
The result is published automatically at
L<http://pod-pandoc.rtfd.io/en/latest/Pod-Pandoc.html>.
=head1 SEE ALSO
This module is based on the wrapper module L<Pandoc> to execute pandoc from Perl
and on the module L<Pandoc::Elements> for pandoc document processing.
This module makes obsolete several specialized C<Pod::Simple::...> modules such
as L<Pod::Simple::HTML>, L<Pod::Simple::XHTML>, L<Pod::Simple::LaTeX>,
L<Pod::Simple::RTF> L<Pod::Simple::Text>, L<Pod::Simple::Wiki>, L<Pod::WordML>,
L<Pod::Perldoc::ToToc> etc. It also covers batch conversion such as
L<Pod::Simple::HTMLBatch>, L<Pod::ProjectDocs>, L<Pod::POM::Web>, and
L<Pod::HtmlTree>.
=encoding utf8
=head1 AUTHOR
Jakob Voß E<lt>jakob.voss@gbv.deE<gt>
=head1 CONTRIBUTORS
Benct Philip Jonsson
=head1 COPYRIGHT AND LICENSE
Copyright 2017- Jakob Voß
GNU General Public License, Version 2
=cut
=begin rst
.. toctree::
:hidden:
:glob:
*
=end rst
|
