ASPEER-MakeMaker-Markdown-Pod

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    markpod --inplace lib/My/Module.pm
    markpod --extract-markdown lib/My/Module.pm > lib/My/Module.pm.md
    markpod --extract-pod lib/My/Module.pm

For processing without MakeMaker, use the engine directly:

    use Markdown::Pod::Embed;

    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

README.md  view on Meta::CPAN

markpod --extract-pod lib/My/Module.pm
```

For processing without MakeMaker, use the engine directly:

```perl
use Markdown::Pod::Embed;

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`:

t/01-embed-process.t  view on Meta::CPAN

1;
__END__

=head1 NAME

Sample::Plain - plain pod only

=cut
PLAIN
    spew($fn, $orig);
    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    is($changed, 0, 'plain POD without markdown reports no changes');
    $markpod_or->markpod_inplace_update($fn);
    is(slurp($fn), $orig, 'plain POD without markdown is preserved');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/embedded.pm";
    spew($fn, <<'EMBEDDED');

t/01-embed-process.t  view on Meta::CPAN


=begin markdown

# NAME

Sample::Embedded - embedded markdown

=end markdown
=cut
EMBEDDED
    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    ok($changed > 0, 'embedded markdown reports changes');
    $markpod_or->markpod_inplace_update($fn);
    my $updated=slurp($fn);
    like($updated, qr/^=begin markdown\b/m, 'embedded markdown block retained');
    like($updated, qr/^=head1 NAME\b/m, 'generated POD added for embedded markdown');
}

{
    my $dir=tempdir(CLEANUP => 1);

t/01-embed-process.t  view on Meta::CPAN


Sample::Sidecar - stale pod

=cut
SIDECAR_PM
    spew("${fn}.md", <<'SIDECAR_MD');
# NAME

Sample::Sidecar - sidecar markdown
SIDECAR_MD
    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    ok($changed > 0, 'sidecar markdown reports changes');
    $markpod_or->markpod_inplace_update($fn);
    my $updated=slurp($fn);
    like($updated, qr/^=begin markdown\b/m, 'sidecar markdown inserted into POD');
    like($updated, qr/Sample::Sidecar - sidecar markdown/, 'sidecar markdown content applied');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/no-pod.pm";
    spew($fn, <<'NO_POD_PM');
package Sample::NoPod;
1;
NO_POD_PM
    spew("${fn}.md", <<'NO_POD_MD');
# NAME

Sample::NoPod - sidecar markdown
NO_POD_MD
    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    is($changed, 1, 'sidecar markdown creates a new POD section');
    $markpod_or->markpod_inplace_update($fn);
    my $updated=slurp($fn);
    like($updated, qr/^__END__$/m, 'new POD section adds __END__ marker');
    like($updated, qr/__END__\n\n=begin markdown\n\n# NAME/, 'new POD section has normalized markdown spacing');
    like($updated, qr/^=begin markdown\b/m, 'sidecar markdown block embedded into file');
    like($updated, qr/^=head1 NAME\b/m, 'generated POD added for new section');
}

t/01-embed-process.t  view on Meta::CPAN

Sample::SidecarOverEmbedded - embedded markdown

=end markdown
=cut
SIDE_EMBED_PM
    spew("${fn}.md", <<'SIDE_EMBED_MD');
# NAME

Sample::SidecarOverEmbedded - sidecar markdown
SIDE_EMBED_MD
    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    ok($changed > 0, 'sidecar overrides embedded markdown');
    $markpod_or->markpod_inplace_update($fn);
    my $updated=slurp($fn);
    like($updated, qr/Sample::SidecarOverEmbedded - sidecar markdown/, 'sidecar markdown content embedded');
    unlike($updated, qr/Sample::SidecarOverEmbedded - embedded markdown/, 'embedded markdown content replaced');
}

{
    my $dir=tempdir(CLEANUP => 1);

t/01-embed-process.t  view on Meta::CPAN

=begin markdown

# DESCRIPTION

Converted section

=end markdown
=cut
MULTI
    spew($fn, $orig);
    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    ok($changed > 0, 'mixed POD reports changes');
    $markpod_or->markpod_inplace_update($fn);
    my $updated=slurp($fn);
    like($updated, qr/Sample::Multi - plain section/, 'plain POD block preserved');
    like($updated, qr/^=head1 DESCRIPTION\b/m, 'markdown-backed POD block regenerated');
}

done_testing;

t/03-update-behavior.t  view on Meta::CPAN


sub spew {
    my ($fn, $content)=@_;
    open my $fh, '>', $fn or die "open $fn: $!";
    print {$fh} $content;
    close $fh or die "close $fn: $!";
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/backup.pm";
    my $orig=<<'PM';
package Sample::Backup;
1;
__END__

=begin markdown

# NAME

Sample::Backup - original markdown

=end markdown
=cut
PM
    spew($fn, $orig);

    my $changed=ASPEER::MakeMaker::Markdown::Pod->new->markpod_process_and_update($fn);
    ok($changed > 0, 'default update changes markdown-backed POD');
    ok(-f "${fn}.bak", 'default update creates backup file');
    is(slurp("${fn}.bak"), $orig, 'backup file preserves original content');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/multi-markdown.pm";
    spew($fn, <<'PM');
package Sample::MultiMarkdown;
1;
__END__

t/03-update-behavior.t  view on Meta::CPAN

=begin markdown

# DESCRIPTION

Second markdown block

=end markdown
=cut
PM

    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    ok($changed > 0, 'multiple markdown-backed POD sections report changes');
    like($markpod_or->markdown, qr/first markdown block.*Second markdown block/s, 'markdown getter contains both sources in order');

    $markpod_or->markpod_inplace_update($fn);
    my $updated=slurp($fn);
    like($updated, qr/^=head1 NAME\b/m, 'first generated heading is present');
    like($updated, qr/^=head1 DESCRIPTION\b/m, 'second generated heading is present');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/end-no-newline.pm";
    spew($fn, "package Sample::EndNoNewline;\n1;\n__END__");
    spew("${fn}.md", <<'MD');
# NAME

Sample::EndNoNewline - sidecar markdown
MD

    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    is($changed, 1, 'sidecar creates POD after existing __END__ without trailing newline');
    $markpod_or->markpod_inplace_update($fn);
    like(slurp($fn), qr/__END__\n\n=begin markdown\n\n# NAME/, 'existing __END__ without trailing newline gets normalized spacing');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/end-extra-blank.pm";
    spew($fn, <<'PM');

t/03-update-behavior.t  view on Meta::CPAN

=begin markdown

# NAME

Sample::EndExtraBlank - embedded markdown

=end markdown
=cut
PM

    my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
    my $changed=$markpod_or->markpod_process($fn);
    ok($changed > 0, 'existing markdown block with extra leading blanks reports changes');
    $markpod_or->markpod_inplace_update($fn);
    like(slurp($fn), qr/__END__\n\n=begin markdown\n\n# NAME/, 'extra blank lines after __END__ are collapsed');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/end-extra-blank-only.pm";
    spew($fn, <<'PM');

t/03-update-behavior.t  view on Meta::CPAN

=end markdown


=head1 NAME

Sample::EndExtraBlankOnly - embedded markdown

=cut
PM

    my $changed=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1})->markpod_process_and_update($fn);
    ok($changed > 0, 'whitespace-only cleanup after __END__ reports a change');
    like(slurp($fn), qr/__END__\n\n=begin markdown\n\n# NAME/, 'whitespace-only cleanup after __END__ is saved');
}

{
    my $dir=tempdir(CLEANUP => 1);
    my $fn="${dir}/end-extra-blank-sidecar.pm";
    spew($fn, <<'PM');
package Sample::EndExtraBlankSidecar;
1;

t/03-update-behavior.t  view on Meta::CPAN


=end markdown
=cut
PM
    spew("${fn}.md", <<'MD');
# NAME

Sample::EndExtraBlankSidecar - sidecar markdown
MD

    my $changed=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1})->markpod_process_and_update($fn);
    ok($changed > 0, 'sidecar update with extra blanks after __END__ reports a change');
    my $updated=slurp($fn);
    like($updated, qr/__END__\n\n=begin markdown\n\n# NAME/, 'sidecar update collapses blank lines after __END__');
    like($updated, qr/sidecar markdown/, 'sidecar content is embedded');
    unlike($updated, qr/embedded markdown/, 'old embedded markdown is replaced');
}

done_testing;



( run in 0.566 second using v1.01-cache-2.11-cpan-99fa8243a42 )