Pod::S...:Pandoc(3pm)

💖 Pod::Simple::Pandoc — the manual, but make it cute 💖

okay bestie, you're reading the man page for Pod::Simple::Pandoc(3pm), from the User Contributed Perl Documentation collection. sit down, hydrate, we're converting Pod to Pandoc and we're gonna slay it. ✨

---

✨ NAME ✨

Pod::Simple::Pandoc — convert Pod to Pandoc document model 🦋

---

🎀 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 ));

that's it. that's the whole vibe. copy-paste it, you're welcome. 💅

---

🌸 DESCRIPTION 🌸

So basically, this module converts Pod format (perlpod) into the document model used by Pandoc <http://pandoc.org/>. The way that it works is you get a result you can poke at with methods from Pandoc::Elements, and then hand off to Pandoc to turn it into literally any other document format you want (HTML, Markdown, LaTeX, PDF, EPUB, docx, ODT, man…) 🔥

Also, go look at pod2pandoc and App::pod2pandoc if you want a command line script and a simplified API to this module. no cap, they're right there. 🫶

---

💅 OPTIONS 💅

• parse — parse Pod data sections with Pandoc and merge them into the document, instead of just passing them along as a "RawBlock". use "*" to parse all formats supported by pandoc as input format. otherwise it expects an array reference. 👑
• podurl — base URL to link Perl module names to. default is <https://metacpan.org/pod/>. 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". 🎀

---

👑 METHODS 👑

parse_file( $filename | *INPUT )

Reads Pod from a file or filehandle and converts it into a Pandoc::Document. The filename gets put into the document metadata field "file" and the module name. And the NAME section, if it's given, is additionally split into the 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 a string and converts it to a Pandoc::Document. Also sets the 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 the metadata field "base" (the relative path from each file to the base directory) on top of "file", "title", and "subtitle". 🦋

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

Same as the "parse_dir" method, except it returns a Pod::Simple::Pandoc::Modules instance that maps module names to Pandoc::Document instances. The source directory can also be specified with the option "source". The 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 codes for filenames ("F<...>") are mapped to inline code with class "filename" (`...`{.filename} in Pandoc Markdown). Formatting codes inside code and filenames (like "code with bold", or <http://example.org/> as a filename) are stripped to unformatted code. Character escapes ("E<...>") and "S<...>" are directly mapped to Unicode characters. The special formatting code "X<...>" is ignored. 💜

🔗 Links 🔗

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

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 are passed as "RawBlock". "HTML", "LaTeX", "TeX", and "tex" are recognized as aliases for "html" and "tex". 🦋

The option "parse" can be used to parse data sections with the pandoc executable and merge them into the result document. ✨

---

🌈 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. 💀

---

okay that's the whole page bestie, go forth and convert 💖 this was perl v5.32.1, dated 2022-01-20, and it lives at Pod::S...:Pandoc(3pm). mwah 💋 periodt. 🎀✨