Pod::Pandoc(3pm) User Contributed Perl Documentation Pod::Pandoc(3pm)

Pod::Pandoc - process Plain Old Documentation format with Pandoc

The Plain Old Documentation format (Pod) is a markup language used to document Perl code (see perlpod for reference). Several Perl modules exist to process and convert Pod into other formats.

Pod::Pandoc is an attempt to unify and extend Pod converting based on the Pandoc <http://pandoc.org/> document converter. Pandoc supports more document formats in a more detailled and uniform way than any set of Perl modules will ever do. For this reason Pod::Pandoc provides methods to convert Pod to the Pandoc document model for further processing with Pandoc.

Installation of this module does not require Pandoc but it is needed to make actual use of it. See <http://pandoc.org/installing.html> for installation.

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

Pandoc option "--toc" corresponds to pod2html option "--index" and is disabled by default. pod2pandoc adds title and subtitle from NAME section.

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

The GitHub wiki of this project <https://github.com/nichtich/Pod-Pandoc/wiki> is automatically populated with its module documentation. 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

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

The result is published automatically at <http://pod-pandoc.rtfd.io/en/latest/Pod-Pandoc.html>.

This module is based on the wrapper module Pandoc to execute pandoc from Perl and on the module Pandoc::Elements for pandoc document processing.

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. It also covers batch conversion such as Pod::Simple::HTMLBatch, Pod::ProjectDocs, Pod::POM::Web, and Pod::HtmlTree.

Jakob Voss <jakob.voss@gbv.de>

Benct Philip Jonsson

Copyright 2017- Jakob Voss

GNU General Public License, Version 2

2022-01-20 perl v5.32.1