Pod::Pandoc(3pm)

💖 Pod::Pandoc 💖

okay so bestie, we're talking about Pod::Pandoc here — the Perl module, living in the User Contributed Perl Documentation section of your friendly neighbourhood man pages. Pull up a chair (or a beanbag, no judgement) and let's get into it 🫶

---

✨ NAME ✨

Pod::Pandoc — process Plain Old Documentation format with Pandoc. that's the whole vibe. no cap 💅

---

🌸 DESCRIPTION 🌸

okay so. Plain Old Documentation format (aka Pod) is a markup language used to document Perl code — if you want the full lore, go read perlpod for reference. and there are, like, several Perl modules out there that exist to process and convert Pod into other formats. a whole little ecosystem, honestly 👑

Pod::Pandoc is an attempt to unify and extend Pod converting based on the Pandoc document converter — that's over at <http://pandoc.org/> if you wanna say hi. and the reason it's doing all this? Pandoc supports more document formats in a more detailled and uniform way than any set of Perl modules will ever do. like, ever. it ate, honestly. 🔥

so for this reason, Pod::Pandoc provides methods to convert Pod to the Pandoc document model for further processing with Pandoc. that's the whole point, periodt ✨

---

🎀 OUTLINE 🎀

here's the little family tree, bestie:

• pod2pandoc is a command line script to convert Pod to any format supported by Pandoc. 🧚
• App::pod2pandoc provides functionality of pod2pandoc to be used in Perl code.
• Pod::Simple::Pandoc converts Pod to the abstract document model of Pandoc.
• Pod::Pandoc::Modules manages a set of Pod documents of Perl modules.

it's giving squad goals 💜

---

🦋 REQUIREMENTS 🦋

okay important thing: installation of this module does not require Pandoc. but — and this is the big but — it is needed to make actual use of it. so like, you can install it and be fine, but the moment you wanna actually do stuff, you need the real thing. go see <http://pandoc.org/installing.html> for installation. 💅

---

🌈 USAGE EXAMPLES 🌈

💖 Replace pod2html 💖

here's the glow-up, side by side:

# pod2html --infile=input.pm --css=style.css --title=TITLE > output.html
pod2pandoc input.pm --css=style.css --toc --name -o output.html

ngl, a couple things to clock here: Pandoc option --toc corresponds to pod2html option --index and is disabled by default. also pod2pandoc adds title and subtitle from the NAME section. so it's basically doing extra homework for you and not even complaining 🫶

---

💜 Replace pod2markdown 💜

# pod2markdown input.pod
pod2pandoc input.pod -t markdown

# pod2markdown input.pod output.md
pod2pandoc input.pod -o output.md

two flavours, same slay ✨

---

👑 GitHub wiki 👑

the GitHub wiki of this project — <https://github.com/nichtich/Pod-Pandoc/wiki> — is automatically populated with its module documentation. iconic behaviour fr fr. wiki pages are created with pod2pandoc as following (see script update-wiki.sh):

pod2pandoc lib/ script/ wiki/ --ext md --index Home --wiki -t markdown_github

automation queen 👑

---

🍓 Sphinx and Read The Docs 🍓

the Sphinx documentation generator — <https://sphinx-doc.org/> — recommends documents in reStructureText format. it further requires a configuration file conf.py, and some links need to be adjusted because Pandoc does not support wikilinks in rst output format (see script 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

and the result is published automatically at <http://pod-pandoc.rtfd.io/en/latest/Pod-Pandoc.html>. full pipeline, zero manual labour, that's the dream 💫

---

🔥 SEE ALSO 🔥

this module is based on the wrapper module Pandoc to execute pandoc from Perl, and on the module Pandoc::Elements for pandoc document processing. two icons holding it up, honestly.

also — and this is kinda wild — this module 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. 💀

and it also covers batch conversion such as:

• Pod::Simple::HTMLBatch
• Pod::ProjectDocs
• Pod::POM::Web
• Pod::HtmlTree

not it casually replacing the entire group chat 😭

---

🌟 AUTHOR 🌟

Jakob Voss <jakob.voss@gbv.de>

---

🎀 CONTRIBUTORS 🎀

Benct Philip Jonsson

---

💅 COPYRIGHT AND LICENSE 💅

Copyright 2017- Jakob Voss

GNU General Public License, Version 2

---

okay that's the whole page bestie, you're officially caught up 🫶 go forth and convert some Pod. this lil doc was brought to you by perl v5.32.1, dated 2022-01-20, from the one and only Pod::Pandoc(3pm) — mwah, bye 💖✨