ASPEER-MakeMaker-Markdown-Pod

 view release on metacpan or  search on metacpan

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

# 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

Converts DocBook article XML beneath `doc/` to sibling Markdown files, then
processes sidecar Markdown files from `MANIFEST` and updates supported Perl
targets in place.

## readme

Renders the project README from Markdown according to the precedence described
above.

## manifest_add

Adds generated support files to `MANIFEST`.

# CAVEATS

This module contains MakeMaker-specific target execution. Hook installation is
provided by `ASPEER::MakeMaker::MM::Import`, and Markdown/POD processing is
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



( run in 1.163 second using v1.01-cache-2.11-cpan-234fa220139 )