ASPEER-MakeMaker-Markdown-Pod
view release on metacpan or search on metacpan
CONTRIBUTING.md view on Meta::CPAN
# Contributing to ASPEER::MakeMaker::Markdown::Pod
Bug reports and focused contributions are welcome. Search the
[GitHub issues](https://github.com/aspeer/pm-ASPEER-MakeMaker-Markdown-Pod/issues)
before opening a new one, and include a minimal reproduction where possible.
Fork the [GitHub repository](https://github.com/aspeer/pm-ASPEER-MakeMaker-Markdown-Pod),
create a topic branch, keep changes focused, and submit a GitHub pull request.
Run `perl Makefile.PL`, `make test`, and `make disttest` before submitting.
Do not include credentials or private data. Report potential vulnerabilities
privately as described in [SECURITY.md](SECURITY.md).
Revision history for ASPEER-MakeMaker-Markdown-Pod
1.014 2026-09-26
- Refer only to the public GitHub repository in installation guidance.
1.013 2026-09-26
- Publish public repository metadata through the GitHub mirror.
- Add contributor and security policies, dependency auditing and
artifact-attestation verification guidance.
- Declare the CPAN authority in distribution metadata.
1.012 2026-09-26
- Separate reusable Markdown processing from MakeMaker integration.
- Add DocBook discovery and sidecar-driven documentation targets.
- Leave the markpod command with Markdown-Pod-Embed.
- Prepare the MakeMaker adapter for its first CPAN release.
- Install pandoc in GitHub Actions for documentation integration tests.
MANIFEST.SKIP
README
README.md
SECURITY.md
t/00-load.t
t/01-embed-process.t
t/02-markdown-source.t
t/03-update-behavior.t
t/04-mm-readme.t
t/05-mm-integration.t
t/data/embedded-sample.pl
t/data/sidecar-sample.pl
t/data/sidecar-sample.pl.md
META.yml Module YAML meta-data (added by MakeMaker)
META.json Module JSON meta-data (added by MakeMaker)
my $markpod = Markdown::Pod::Embed->new({
dialect => 'GitHub',
nobackup => 1,
});
my $changed = $markpod->markpod_process_and_update('lib/My/Module.pm');
The MakeMaker import hook adds doc and readme targets to the generated
Makefile. It also retains the project's established MakeMaker
configuration, dependency, metadata, provenance, and install-map
behavior.
The same complete integration can be enabled optionally inside
Makefile.PL:
use ExtUtils::MakeMaker;
eval {
require ASPEER::MakeMaker::Markdown::Pod;
ASPEER::MakeMaker::Markdown::Pod->import();
my $markpod = Markdown::Pod::Embed->new({
dialect => 'GitHub',
nobackup => 1,
});
my $changed = $markpod->markpod_process_and_update('lib/My/Module.pm');
```
The MakeMaker import hook adds `doc` and `readme` targets to the generated
Makefile. It also retains the project's established MakeMaker configuration,
dependency, metadata, provenance, and install-map behavior.
The same complete integration can be enabled optionally inside `Makefile.PL`:
```perl
use ExtUtils::MakeMaker;
eval {
require ASPEER::MakeMaker::Markdown::Pod;
ASPEER::MakeMaker::Markdown::Pod->import();
1;
SECURITY.md view on Meta::CPAN
Please include enough detail to reproduce and assess the issue, including:
- the affected ASPEER::MakeMaker::Markdown::Pod version
- the affected Perl version and operating system, if relevant
- a proof of concept, test case, or reproduction steps
- relevant logs, code snippets, configuration, or request/response examples
- whether the issue is known to be actively exploited
- whether you want public credit when the issue is disclosed
Do not include passwords, tokens, private keys, personal data, or other
sensitive information in the report unless it is strictly necessary and safe
to share with the maintainers.
If you would like help triaging the issue, need CVE coordination, cannot reach
the maintainer, or believe the issue is being actively exploited, you may also
copy the CPAN Security Group (CPANSec):
cpan-security@security.metacpan.org
For signs of a compromised CPAN/PAUSE account, contact the PAUSE
lib/ASPEER/MakeMaker/Markdown/Pod.pm view on Meta::CPAN
```text
perl -MASPEER::MakeMaker::Markdown::Pod Makefile.PL
```
# DESCRIPTION
`ASPEER::MakeMaker::Markdown::Pod` integrates documentation maintenance and the project's
established distribution conventions with `ExtUtils::MakeMaker`. Importing it
from `Makefile.PL` installs the MakeMaker lifecycle hooks used to configure the
generated Makefile, package metadata and install map, Git-SHA provenance, and
documentation targets. The generated global `PERLRUN` preserves
the active local library paths and MakeMaker extensions.
The responsibilities are deliberately separated:
- `ASPEER::MakeMaker::Markdown::Pod` inherits the common MakeMaker behavior
from `ASPEER::MakeMaker`.
- `ASPEER::MakeMaker::MM::Import` installs and implements the MakeMaker
lifecycle hooks.
- `ASPEER::MakeMaker::Markdown::Pod::MM` generates and executes the `doc` and `readme`
lib/ASPEER/MakeMaker/Markdown/Pod.pm view on Meta::CPAN
command-line activation is:
perl -MASPEER::MakeMaker::Markdown::Pod Makefile.PL
=head1 DESCRIPTION
C<ASPEER::MakeMaker::Markdown::Pod> integrates documentation maintenance and the project's
established distribution conventions with C<ExtUtils::MakeMaker>. Importing it
from C<Makefile.PL> installs the MakeMaker lifecycle hooks used to configure the
generated Makefile, package metadata and install map, Git-SHA provenance, and
documentation targets. The generated global C<PERLRUN> preserves
the active local library paths and MakeMaker extensions.
The responsibilities are deliberately separated:
=over
=item -
C<ASPEER::MakeMaker::Markdown::Pod> inherits the common MakeMaker behavior
lib/ASPEER/MakeMaker/Markdown/Pod.pm.md view on Meta::CPAN
```text
perl -MASPEER::MakeMaker::Markdown::Pod Makefile.PL
```
# DESCRIPTION
`ASPEER::MakeMaker::Markdown::Pod` integrates documentation maintenance and the project's
established distribution conventions with `ExtUtils::MakeMaker`. Importing it
from `Makefile.PL` installs the MakeMaker lifecycle hooks used to configure the
generated Makefile, package metadata and install map, Git-SHA provenance, and
documentation targets. The generated global `PERLRUN` preserves
the active local library paths and MakeMaker extensions.
The responsibilities are deliberately separated:
- `ASPEER::MakeMaker::Markdown::Pod` inherits the common MakeMaker behavior
from `ASPEER::MakeMaker`.
- `ASPEER::MakeMaker::MM::Import` installs and implements the MakeMaker
lifecycle hooks.
- `ASPEER::MakeMaker::Markdown::Pod::MM` generates and executes the `doc` and `readme`
t/05-mm-integration.t view on Meta::CPAN
like($makefile, qr/^readme ::$/m, 'readme target generated');
like($makefile,
qr/^MARKPOD_PM_TARGET=\$\(PERLRUN\) -M\$\(MARKPOD_PM\).*\s-e\s/m,
'target command explicitly reloads its dispatch module');
unlike($makefile, qr/^MM_PREFIX\s*=/m,
'private macro prefix configuration is not emitted');
like($makefile, qr/^\s*\@\$\(MARKPOD_PM_TARGET\) doc$/m,
'doc target passes its method explicitly');
like($makefile, qr/^LICENSE\s*=\s*perl$/m, 'license macro generated');
like(slurp('MYMETA.json'), qr/"license"\s*:\s*\[/,
'license metadata generated');
like($makefile, qr/^EXE_FILES\s*=\s*bin\/sample\.pl$/m,
'executable retains its declared filename');
ok(!-e 'bin/sample', 'extensionless executable is not created implicitly');
unlike($makefile, qr/lib\/Sample\.pm\.md\s+blib\//,
'Markdown sidecar excluded from install map');
like($makefile, qr/'LICENSE'\s+'\$\(INST_LIBDIR\)/,
'license file included in install map');
if (length($git_sha)) {
is(slurp('lib/Sample.pm.sha'), "$git_sha\n", 'Git-SHA provenance generated');
like($makefile, qr/lib\/Sample\.pm\.sha/, 'Git-SHA provenance included in install map');
t/05-mm-integration.t view on Meta::CPAN
# Command-line and embedded activation together remain idempotent
#
is(system($^X, '-MASPEER::MakeMaker::Markdown::Pod', 'Makefile.PL'), 0,
'combined command-line and embedded activation succeeds');
$makefile=slurp('Makefile');
@doc_target=($makefile=~/^doc :: readme$/mg);
is(scalar(@doc_target), 1, 'combined activation generates one doc target');
# Install executable Git provenance as data rather than as another executable
#
blurp('Makefile.PL', <<'MAKEFILE_PL');
use strict;
use warnings;
use ExtUtils::MakeMaker;
WriteMakefile(
NAME => 'Sample',
VERSION_FROM => 'bin/sample.pl',
EXE_FILES => ['bin/sample.pl'],
LICENSE => 'perl',
t/05-mm-integration.t view on Meta::CPAN
VERSION => '0.001',
LICENSE => 'perl',
AUTHOR => 'Andrew Speer',
);
MAKEFILE_PL
is(system($^X, '-MASPEER::MakeMaker::Markdown::Pod', 'Makefile.PL'), 0,
'Makefile.PL succeeds without VERSION_FROM');
ok(!-e '.sha', 'Git-SHA provenance is not created without VERSION_FROM');
# The documented minimal configuration does not require metadata fields
#
blurp('Makefile.PL', <<'MAKEFILE_PL');
use strict;
use warnings;
use ExtUtils::MakeMaker;
WriteMakefile(
NAME => 'Sample',
VERSION_FROM => 'lib/Sample.pm',
);
MAKEFILE_PL
is(system($^X, '-MASPEER::MakeMaker::Markdown::Pod', 'Makefile.PL'), 0,
'minimal Makefile.PL succeeds without LICENSE or AUTHOR');
$makefile=slurp('Makefile');
like($makefile, qr/^doc :: readme$/m,
'minimal Makefile.PL retains documentation targets');
chdir($cwd) || die "unable to chdir $cwd, $!";
# File writes must report both data and close failures
#
{
no warnings qw(redefine);
local *IO::File::new=sub {bless({}, 'Local::FailingWrite')};
my $write_ok=eval {
ASPEER::MakeMaker::MM::Util::blurp('ignored', 'text');
1;
};
ok(!$write_ok, 'file write failure is fatal');
}
( run in 2.424 seconds using v1.01-cache-2.11-cpan-16aabcbfbcb )