/ 
Dist-Zilla-Plugin-UsefulReadme-v0.5.0
/ Dist::Zilla::Plugin::UsefulReadme

NAME

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

VERSION

version v0.5.0

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 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 that works better with Pod::Weaver.

CONFIGURATION OPTIONS

source

This is the path to the module that will be used for generating the README.

It will default to the main module.

phase

This is the phase to generate the README.

Allowed values are build (default) or release.

location

This is where the new README will be saved.

Allowed values are build (default) or the distribution root.

encoding

The encoding of the POD. Defaults to utf8. See Encode::Supported.

This was added in v0.2.0.

section_fallback

If one of the "sections" does not exist in the POD, then generate one for the README. It is true by default but cal be disabled, e.g.

fallback = 0

sections

This is a list of =head1 sections to be included in the README. It can be specified multiple times using the section option.

This can either be a case-insensitive string, or a regex that implicitly matches the entire heading, surrounded by slashes.

The default is equivalent to specifying

section = name
section = synopsis
section = description
section = recent changes
section = requirements
section = installation
section = /support|bugs/
section = source
section = /authors?/
section = /contributors?/
section = /copyright|license|copyright and license/
section = see also

The version, requirements, installation and recent changes sections are special. If they do not exist in the module POD, then default values will be used for them unless "section_fallback" is false.

This will also include =head1 sections in "regions" marked as readme, normally used for Pod::Readme:

=begin :readme

=head1 REQUIREMENTS

This should only be visible in the README.

=end :readme

If you want to amend one of the generated fallback sections akin to Pod::Weaver::Plugin::AppendPrepend, you must specify them inside of readme regions.

To append something to the end of a generated section:

=begin :readme

=head1 append:INSTALLATION

Remember to bring a towel.

=end :readme

To prepend something to the beginning of a generated section:

=begin :readme

=head1 prepend:REQUIREMENTS

This requires L<libexample|http://www.example.org> to be installed on your system.

=end :readme

Note that multiple append and prepend blocks must be in separate region blocks.

type

This is the file to generate the README.

Allowed values are pod, text (default), markdown, gfm (GitHub-flavoured markdown) or custom.

Note that the "filename" will have a different default, depending on the type.

If custom is chosen, then you must specify a "filename" and "parser_class".

parser_class

This is the POD parser class, based on the "type".

filename

This is the filename to use, e.g. README or REAME.md.

regions

This is a list of regions inside of =for or =begin/=end paragraphs to be included in any sections.

By default, it includes stopwords, Pod::Coverage, and Test::MixedScripts.

You may need to override this to include other region types, e.g.

type = markdown
region = markdown
region = stopwords
region = Pod::Coverage

Note that this is not updated automatically from the "type" because how regions are embedded in POD varies too widely to assume that it is always safe to include arbitrary regions with the same name.

The readme region is not included since that has a special meaning to indicate sections that are included only in the README file.

This was added in v0.2.0.

SEE ALSO

Dist::Zilla

Pod::Weaver

Pod::Readme

Dist::Zilla::Plugin::Readme::Brief

Dist::Zilla::Plugin::ReadmeAnyFromPod

SUPPORT

Only the latest version of this module will be supported.

This module requires Perl v5.20 or later. Future releases may only support Perl versions released in the last ten years.

Reporting Bugs and Submitting Feature Requests

Please report any bugs or feature requests on the bugtracker website https://github.com/robrwo/perl-Dist-Zilla-Plugin-UsefulReadme/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

If the bug you are reporting has security implications which make it inappropriate to send to a public issue tracker, then see SECURITY.md for instructions how to report security vulnerabilities.

SOURCE

The development version is on github at https://github.com/robrwo/perl-Dist-Zilla-Plugin-UsefulReadme and may be cloned from git://github.com/robrwo/perl-Dist-Zilla-Plugin-UsefulReadme.git

AUTHOR

Robert Rothenberg <[email protected]>

Some of this code was adapted from similar code in Dist::Zilla::Plugin::ReadmeAnyFromPod and Dist::Zilla::Plugin::Readme::Brief.

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Robert Rothenberg.

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