Pod::Simple::Pandoc¶
SYNOPSIS¶
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 ));
DESCRIPTION¶
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.
OPTIONS¶
- parse
- 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. - podurl
- 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 classperl-module
.
METHODS¶
parse_file( $filename | *INPUT )¶
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
.
parse_module( $module )¶
Reads Pod from a module given by name such as "Pod::Pandoc"
or
by URL.
parse_string( $string )¶
Reads Pod from string and convert it to a
Pandoc::Document. Also
sets metadata fields title
and subtitle
.
parse_dir( $directory )¶
Recursively looks for .pm
and .pod
files in a given
directory and parses them. Returns a hash reference with filenames
mapped to
Pandoc::Documentobjects. Each document is enriched with metadata fields base
(relative path from each file to the base directory) in addition to
file
, title
, and subtitle
.
parse_modules( $directory, [ quiet => 0|1 ] )¶
Same as method parse_dir
but returns a
Pod::Simple::Pandoc::Modulesinstance that maps module names to
Pandoc::Documentinstances. The source directory can also be specified with option
source
. Option quiet
disables warnings for skipped files.
parse_and_merge( @files_or_modules )¶
Reads Pod from files or modules given by name and merges them into one Pandoc::Document by concatenation.
MAPPING¶
Pod elements are mapped to Pandoc elements as following:
Formatting codes¶
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.
Titles may contain formatting ``codes``!¶
Lists¶
Numbered lists are
converted to
NumberedList
andBulleted lists are
converted to
BulletList
Definition Lists are
also supported.
=over/=back¶
An=over
…=back
region containing no=item
is mapped toBlockQuote
.
Verbatim sections¶
verbatim sections are mapped
to code blocks
Data sections¶
Data sections are passed as RawBlock
. HTML
, LaTeX
,
TeX
, and tex
are recognized as alias for html
and
tex
.
Option parse
can be used to parse data sections with pandoc
executable and merge them into the result document.
HTML is passed through as you can see here.
<div>...</div>
if needed.SEE ALSO¶
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::RTFPod::Simple::Text,
Pod::Simple::Wiki,
Pod::WordML,
Pod::Perldoc::ToTocetc.