Pod::Simple::Pandoc - convert Pod to Pandoc document model
use Pod::Simple::Pandoc; my $parser = Pod::Simple::Pandoc->new( %options ); my $doc = $parser->parse_file( $filename ); # result is a Pandoc::Document object my $json = $doc->to_json; my $markdown = $doc->to_pandoc( -t => 'markdown' ); $doc->to_pandoc(qw( -o doc.html --standalone ));
This module converts Pod format (perlpod) to the document model used by Pandoc. The result can be accessed with methods of Pandoc::Elements and further processed with Pandoc to convert it to other document formats (HTML, Markdown, LaTeX, PDF, EPUB, docx, ODT, man...).
See pod2pandoc and App::pod2pandoc for a command line script and a simplified API to this module.
Parse Pod data sections with Pandoc and merge them into the document instead of passing them as RawBlock. Use * to parse all formats supported by pandoc as input format. Expects an array reference otherwise.
RawBlock
*
Base URL to link Perl module names to. Set to https://metacpan.org/pod/ by default. A false value disables linking external modules and wraps module names in Span elements instead. All module names are marked up with class perl-module.
Span
perl-module
Reads Pod from file or filehandle and convert it to a Pandoc::Document. The filename is put into document metadata field file and the module name. The NAME section, if given, is additionally split into metadata fields title and subtitle.
file
title
subtitle
Reads Pod from a module given by name such as "Pod::Pandoc" or by URL.
"Pod::Pandoc"
Reads Pod from string and convert it to a Pandoc::Document. Also sets metadata fields title and subtitle.
Recursively looks for .pm and .pod files in a given directory and parses them. Returns a hash reference with filenames mapped to Pandoc::Document objects. Each document is enriched with metadata fields base (relative path from each file to the base directory) in addition to file, title, and subtitle.
.pm
.pod
base
Same as method parse_dir but returns a Pod::Simple::Pandoc::Modules instance that maps module names to Pandoc::Document instances. The source directory can also be specified with option source. Option quiet disables warnings for skipped files.
parse_dir
source
quiet
Reads Pod from files or modules given by name and merges them into one Pandoc::Document by concatenation.
Pod elements are mapped to Pandoc elements as following:
Formatting codes for italic text (I<...>), bold text (B<...>), and code (C<...>) are mapped to Emphasized text (Emph), strongly emphasized text (Strong), and inline code (Code). Formatting code for filenames (F<...>) are mapped to inline code with class filename (`...`{.filename} in Pandoc Markdown). Formatting codes inside code and filenames (e.g. code with bold or http://example.org/ as filename) are stripped to unformatted code. Character escapes (E<...>) and S<...> are directly mapped to Unicode characters. The special formatting code X<...> is ignored.
I<...>
B<...>
code
C<...>
Emph
Strong
Code
F<...>
filename
`...`{.filename}
code with bold
E<...>
S<...>
X<...>
Some examples of links of different kinds:
http://example.org/
pod2pandoc
"OPTIONS" in pod2pandoc
perl(1)
"ENVIRONMENT" in crontab(5)
hell itself!
Link text can contain formatting codes:
the pod2pandoc script
"MAPPING"
mapping from PoD to Pandoc
codes
Numbered lists are
converted to NumberedList and
NumberedList
Bulleted lists are
converted to
BulletList
also supported.
An =over...=back region containing no =item is mapped to BlockQuote.
=over
=back
=item
BlockQuote
verbatim sections are mapped to code blocks
Data sections are passed as RawBlock. HTML, LaTeX, TeX, and tex are recognized as alias for html and tex.
HTML
LaTeX
TeX
tex
html
Option parse can be used to parse data sections with pandoc executable and merge them into the result document.
parse
HTML is passed through as you can see here.
<div>...</div>
This module is based on Pod::Simple (Pod::Simple::SimpleTree). It makes obsolete several specialized Pod::Simple::... modules such as Pod::Simple::HTML, Pod::Simple::XHTML, Pod::Simple::LaTeX, Pod::Simple::RTF Pod::Simple::Text, Pod::Simple::Wiki, Pod::WordML, Pod::Perldoc::ToToc etc.
Pod::Simple::...
To install Pod::Pandoc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Pandoc
CPAN shell
perl -MCPAN -e shell install Pod::Pandoc
For more information on module installation, please visit the detailed CPAN module installation guide.