view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

Dist::Zilla::Plugin::UsefulReadme - generate a README file with the useful bits

# SYNOPSIS

In the `dist.ini`

```
[UsefulReadme]
type     = markdown
filename = README.md
phase    = build
location = build
section = name
section = synopsis
section = description
section = requirements
section = installation
section = bugs
section = source
section = author
section = copyright and license
section = see also
```

# DESCRIPTION

This is a [Dist::Zilla](https://metacpan.org/pod/Dist%3A%3AZilla) plugin to filter the main module POD to generate a `README` file.  It allows developers to
determine which sections are incorporated into the `README` rather than dumping the entire main module documentation.

This also supports including special sections for showing the most recent entry in the `Changes` file, showing the
runtime requirements, and including installation instructions.

This was written as a successor to [Pod::Readme](https://metacpan.org/pod/Pod%3A%3AReadme) that works better with [Pod::Weaver](https://metacpan.org/pod/Pod%3A%3AWeaver).

# RECENT CHANGES

Changes for version v0.5.2 (2025-10-19)

- Enhancements
    - The STATUS and SECURITY CONSIDERATIONS sections are included by default.
- Documentation
    - Updated the SUPPORT section to clarify the minimum Perl version.
- Tests
    - Add more author tests.

See the `Changes` file for more details.

# REQUIREMENTS

This module lists the following modules as runtime dependencies:

- [CPAN::Changes::Parser](https://metacpan.org/pod/CPAN%3A%3AChanges%3A%3AParser) version 0.500002 or later
- [Dist::Zilla](https://metacpan.org/pod/Dist%3A%3AZilla) version 6.003 or later
- [Hash::Ordered](https://metacpan.org/pod/Hash%3A%3AOrdered) version 0.005 or later
- [List::Util](https://metacpan.org/pod/List%3A%3AUtil) version 1.33 or later
- [Module::Metadata](https://metacpan.org/pod/Module%3A%3AMetadata) version 1.000015 or later
- [Module::Runtime](https://metacpan.org/pod/Module%3A%3ARuntime)
- [Moose](https://metacpan.org/pod/Moose)
- [MooseX::MungeHas](https://metacpan.org/pod/MooseX%3A%3AMungeHas)
- [PPI::Token::Pod](https://metacpan.org/pod/PPI%3A%3AToken%3A%3APod)
- [Path::Tiny](https://metacpan.org/pod/Path%3A%3ATiny)
- [Perl::PrereqScanner](https://metacpan.org/pod/Perl%3A%3APrereqScanner) version 1.024 or later
- [Pod::Elemental](https://metacpan.org/pod/Pod%3A%3AElemental)
- [Pod::Simple](https://metacpan.org/pod/Pod%3A%3ASimple) version 3.23 or later
- [Pod::Weaver::Role::Section](https://metacpan.org/pod/Pod%3A%3AWeaver%3A%3ARole%3A%3ASection)
- [Types::Common](https://metacpan.org/pod/Types%3A%3ACommon)
- [experimental](https://metacpan.org/pod/experimental)
- [namespace::autoclean](https://metacpan.org/pod/namespace%3A%3Aautoclean)
- [perl](https://metacpan.org/pod/perl) version v5.20.0 or later

See the `cpanfile` file for the full list of prerequisites.

# INSTALLATION

The latest version of this module (along with any dependencies) can be installed from [CPAN](https://www.cpan.org) with the `cpan` tool that is included with Perl: