ASPEER-MakeMaker-Markdown-Pod

 view release on metacpan or  search on metacpan

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

    else {
        msg('markpod: %s -> %s: finished, no changes', $source_fn, $readme_fn);
    }

    push @manifest_add, $readme_fn unless exists $manifest_hr->{$readme_fn};
    manifest_add(\@manifest_add) if @manifest_add;

}


sub manifest_add {

    my ($file_ar)=@_;
    return undef unless @{$file_ar};
    require ExtUtils::Manifest;
    my %add=map { $_ => '' } @{$file_ar};
    ExtUtils::Manifest::maniadd(\%add);
    return 1;

}


1;


__END__

=begin markdown

# NAME

ASPEER::MakeMaker::Markdown::Pod::MM - MakeMaker integration for ASPEER::MakeMaker::Markdown::Pod

# SYNOPSIS

In `Makefile.PL`:

```perl
BEGIN {
    use lib './lib';
    eval {
        require ASPEER::MakeMaker::Markdown::Pod;
        ASPEER::MakeMaker::Markdown::Pod->import;
        1;
    };
}
```

Then run:

```bash
perl Makefile.PL
make doc
make readme
```

# DESCRIPTION

`ASPEER::MakeMaker::Markdown::Pod::MM` generates and executes the documentation targets
used by `ExtUtils::MakeMaker`. DocBook article conversion is delegated to
`Docbook::Convert::Pandoc`. Markdown source selection, Markdown-to-POD conversion,
and Perl source updates are delegated to `Markdown::Pod::Embed`.

This class inherits the common MakeMaker namespace from
`ASPEER::MakeMaker::MM` and imports shared helper functions from
`ASPEER::MakeMaker::MM::Util`.

`ASPEER::MakeMaker::MM::Import` installs the MakeMaker lifecycle hooks and
appends the target template. This module handles the resulting `doc` and
`readme` invocations.

# MAKEFILE INTEGRATION

The module adds a postamble fragment containing targets that invoke
`ASPEER::MakeMaker::Markdown::Pod::MM` from the generated Makefile.

`doc`
: Recursively converts DocBook article XML beneath `doc/` to sibling Markdown
  files without using `MANIFEST` as a discovery list. It then finds Markdown
  files listed in `MANIFEST`, derives each target by removing the trailing
  `.md`, and merges supported sidecars into matching `.pm`, `.pl`, or executable
  files. Markdown files under `t/` are ignored so test fixtures are not rewritten.

`readme`
: Builds `README` from the best available Markdown source.

The generated status output is concise and goes to STDERR:

```text
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
```

Unsupported or missing targets are reported only when verbose output has been
enabled.

# README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

1. If `README.md` exists, it is used to generate or update `README`.
2. If `README` exists without `README.md`, both are left unchanged.
3. If neither exists, Markdown is obtained from the sidecar or embedded
   documentation of the file named by `VERSION_FROM` and written to a new,
   regular `README.md` file. `README` is then rendered from that file.
4. If the `VERSION_FROM` file has no sidecar or embedded Markdown, no README
   file is created.

The module never creates a `VERSION_FROM.md` sidecar. Generated README files are
added to `MANIFEST`.

`Markdown::Pod::Embed` renders the Markdown to plain text with `pandoc`.

# FUNCTIONS

## arg

Converts the positional arguments passed through the generated Makefile target
into a named hash used by `doc` and `readme`.

## doc

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

isolated in `Markdown::Pod::Embed`.

The implementation expects a traditional MakeMaker distribution layout with a
usable `MANIFEST` file.

# SEE ALSO

`ASPEER::MakeMaker::Markdown::Pod`, `ASPEER::MakeMaker::MM::Import`,
`Markdown::Pod::Embed`, `ExtUtils::MakeMaker`, `ExtUtils::Manifest`

# AUTHOR

Andrew Speer <andrew.speer@isolutions.com.au>

# LICENSE AND COPYRIGHT

This file is part of ASPEER::MakeMaker::Markdown::Pod.

This software is copyright (c) 2026 by Andrew Speer
<andrew.speer@isolutions.com.au>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

Full license text is available at:

<http://dev.perl.org/licenses/>

=end markdown


=head1 NAME

ASPEER::MakeMaker::Markdown::Pod::MM - MakeMaker integration for ASPEER::MakeMaker::Markdown::Pod


=head1 SYNOPSIS

In C<Makefile.PL>:


 BEGIN {
     use lib './lib';
     eval {
         require ASPEER::MakeMaker::Markdown::Pod;
         ASPEER::MakeMaker::Markdown::Pod->import;
         1;
     };
 }
Then run:


 perl Makefile.PL
 make doc
 make readme

=head1 DESCRIPTION

C<ASPEER::MakeMaker::Markdown::Pod::MM> generates and executes the documentation targets
used by C<ExtUtils::MakeMaker>. DocBook article conversion is delegated to
C<Docbook::Convert::Pandoc>. Markdown source selection, Markdown-to-POD conversion,
and Perl source updates are delegated to C<Markdown::Pod::Embed>.

This class inherits the common MakeMaker namespace from
C<ASPEER::MakeMaker::MM> and imports shared helper functions from
C<ASPEER::MakeMaker::MM::Util>.

C<ASPEER::MakeMaker::MM::Import> installs the MakeMaker lifecycle hooks and
appends the target template. This module handles the resulting C<doc> and
C<readme> invocations.


=head1 MAKEFILE INTEGRATION

The module adds a postamble fragment containing targets that invoke
C<ASPEER::MakeMaker::Markdown::Pod::MM> from the generated Makefile.

C<doc>
: Recursively converts DocBook article XML beneath C<doc/> to sibling Markdown
  files without using C<MANIFEST> as a discovery list. It then finds Markdown
  files listed in C<MANIFEST>, derives each target by removing the trailing
  C<.md>, and merges supported sidecars into matching C<.pm>, C<.pl>, or executable
  files. Markdown files under C<t/> are ignored so test fixtures are not rewritten.

C<readme>
: Builds C<README> from the best available Markdown source.

The generated status output is concise and goes to STDERR:


 markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
 markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
Unsupported or missing targets are reported only when verbose output has been
enabled.


=head1 README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

=over

=item 1.

If C<README.md> exists, it is used to generate or update C<README>.


=item 2.

If C<README> exists without C<README.md>, both are left unchanged.


=item 3.

If neither exists, Markdown is obtained from the sidecar or embedded
   documentation of the file named by C<VERSION_FROM> and written to a new,
   regular C<README.md> file. C<README> is then rendered from that file.


=item 4.



( run in 1.760 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )