Task::Markdown::Pod

Task::Markdown::Pod installs the complete Perl toolchain for converting Markdown sidecars and DocBook documents into POD for Perl distributions. The supported DocBook path converts DocBook to Markdown first; the Markdown/POD processor then maintains POD in Perl sources. The bundle includes the MakeMaker integration used by make doc and make readme.

Installation

Install the released bundle and its Perl prerequisites from CPAN:

cpanm Task::Markdown::Pod

The bundle installs these distributions:

• Markdown::Pod::Embed for Markdown-to-POD conversion and the markpod command;
• Docbook::Convert for DocBook-to-Markdown conversion and the docbook-convert command;
• ASPEER::MakeMaker::Markdown::Pod for the doc and readme MakeMaker targets.

System prerequisites

CPAN installs the Perl modules, but it does not install external programs. Install Pandoc for the preferred DocBook conversion pipeline and README generation. Install xmllint and xsltproc for the DocBook XML toolchain. On Fedora, a complete build environment can be installed with:

sudo dnf install perl perl-App-cpanminus perl-devel make gcc expat-devel \
  pandoc libxml2 libxslt

perl-devel, gcc, make, and expat-devel allow CPAN to build XML parser dependencies when a suitable Fedora Perl package is not already installed.

Use

Convert a Markdown sidecar into embedded POD:

markpod --inplace lib/My/Module.pm

Convert a DocBook article to Markdown:

docbook-convert --pandoc doc/guide.xml > doc/guide.md

Enable the MakeMaker targets in a distribution:

use ExtUtils::MakeMaker;
use ASPEER::MakeMaker::Markdown::Pod;

WriteMakefile(
    NAME         => 'My::Module',
    VERSION_FROM => 'lib/My/Module.pm',
);

Then run:

perl Makefile.PL
make doc
make readme

GitHub attestations

Tagged releases build one distribution archive, publish it to GitHub Releases and CPAN, and attach GitHub provenance and a Sigstore bundle. After downloading Task-Markdown-Pod-VERSION.tar.gz from CPAN, verify its attestation with:

gh attestation verify Task-Markdown-Pod-VERSION.tar.gz \
  --repo aspeer/pm-Task-Markdown-Pod

Author

Andrew Speer andrew.speer@isolutions.com.au

License and copyright

This software is copyright (c) 2026 by Andrew Speer. It may be distributed under the same terms as Perl itself.