/ 
Pod-Pandoc-0.3.0
River stage zero No dependents
/ Pod::Simple::Pandoc

NAME

Pod::Simple::Pandoc - convert Pod to Pandoc document model

SYNOPSIS

use Pod::Simple::Pandoc;

my $parser = Pod::Simple::Pandoc->new;
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 documentation (perlpod) to the document model used by Pandoc. The result object can be accessed with methods of Pandoc::Elements and emitted as JSON for further processing to other document formats (HTML, Markdown, LaTeX, PDF, EPUB, docx, ODT, man...).

The command line script pod2pandoc makes use of this module, for instance to directly convert to PDF:

pod2pandoc input.pod -o output.pdf

OPTIONS

data-sections

Parse data sections of pandoc input formats with Pandoc and merge them into the document (disabled by default).

podurl

Base URL to link Perl module names to. Set to https://metacpan.org/pod/ by default.

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_and_merge( @files_or_modules )

Reads Pod from files or modules given by name and merges them into one Pandoc::Document by concatenation.

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::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.

parse_modules( $directory, [ quiet => 0|1 ] )

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.

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.

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

Internal links are not supported yet:

"MAPPING"

mapping from PoD to Pandoc

Titles may contain formatting codes!

Lists

  1. Numbered lists are

  2. converted to NumberedList and

    • Bulleted lists are

    • converted to

      BulletList

Definition
Lists
are

also supported.

=over/=back

    An =over...=back region containing no =item is mapped to BlockQuote.

Verbatim sections

verbatim sections are mapped
  to code blocks

Data sections

Data sections with target html or latex are passed as RawBlock. HTML, LaTeX, TeX, and tex are recognized as alias.

With option parse-data-sections additional targets supported by pandoc as input format (markdown, markdown_github, rst...) are parsed with Pandoc and merged into the result document.

HTML is passed through as you can see here.

HTML is automatically enclosed in <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::RTF Pod::Simple::Text, Pod::Simple::Wiki, Pod::WordML, Pod::Perldoc::ToToc etc.