Dist::Zilla::Plugin::Readme::Brief - Provide a short simple README with just the essentials
version 0.003003
[Readme::Brief] ; Override autodetected install method installer = eumm ; Override autodetected main_module or main_module.pod as a source source_file = lib/Path/To/Module.pm ; Override name to use for brief body description_label = WHAT IS THIS
This provides a terse but informative README file for your CPAN distribution that contains just the essential details about your dist a casual consumer would want to know.
The name of the primary module in the distribution
The distribution's main modules description
Simple installation instructions from an extracted archive
Short copyright information
This is still reasonably fresh code and reasonably experimental, and feature enhancements and bug fixes are actively desired.
However, bugs are highly likely to be encountered, especially as there are no tests.
Heading is derived from the package statement in the source_file
package
source_file
Description is extracted as the entire H1Nest of the section titled DESCRIPTION ( or whatever description_label is ) in the source_file
H1Nest
DESCRIPTION
description_label
Installation instructions are automatically determined by the presence of either
A Makefile.PL file in your dist ( Where it assumes EUMM style )
Makefile.PL
EUMM
A Build.PL file in your dist ( where it assumes Module::Build style )
Build.PL
Module::Build
In the case of both, only instructions for Makefile.PL will be emitted.
All of the above behavior can be overridden using the installer attribute.
installer
ALL Copyright and license details are extracted from the source_file in any H1Nest that has either COPYRIGHT or LICENSE in the heading.
COPYRIGHT
LICENSE
Or failing such a section, a COPYRIGHT AND LICENSE section will be derived from zilla->license
COPYRIGHT AND LICENSE
zilla->license
Determines the file that will be parsed for POD to populate the README from.
By default, it uses your main_module, except if you have a .pod file with the same basename and path as your main_module, in which case it uses that.
main_module
.pod
This parameter and associated .pod support is new in v0.003000
v0.003000
Determines what installers to document in the INSTALLATION section.
INSTALLATION
By default, that section is determined based on the presence of certain files in your dist.
dist
However, in the event you have multiple installers supported, manually specifying this attribute allows you to control which, or all, and the order.
installer = eumm ; # only eumm installer = eumm installer = mb ; EUMM shown first, MB shown second installer = mb installer = eumm ; EUMM shown second, MB shown first
The verbiage however has not yet been cleaned up such that having both is completely lucid.
This parameter was introduced in version v0.002000
v0.002000
This case-insensitive attribute defines what =head1 node will be used for the description section of the brief.
=head1
By default, this is DESCRIPTION.
This parameter was introduced in version v0.003000
Here are some competing modules and how this module differs from them.
[Readme]
Gives a much briefer more generic README file, which lacks quite as much readable content, and contains no installation instructions.
README
[ReadmeFromPod]
Provides various output formats, but ultimately is a transformer of your source_file's POD, which is excessive for some peoples tastes. ( And lacks install instructions )
POD
[ReadmeAnyFromPod]
Based on the above provides a bunch of extra features, but is ultimately limited in similar ways with regards to install details and verbosity.
[Pod2Readme]
Possibly the most straight forward POD → README translator, but limited like the above in that it is only a POD translator, but lacks the install instructions aspect.
[InstallGuide]
The polar opposite approach that only focuses on elaborate installation instructions in INSTALL, but lacks any of the POD and COPYRIGHT elements.
INSTALL
Kent Fredric <kentnl@cpan.org>
This software is copyright (c) 2020 by Kent Fredric <kentfredric@gmail.com>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Dist::Zilla::Plugin::Readme::Brief, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Plugin::Readme::Brief
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Plugin::Readme::Brief
For more information on module installation, please visit the detailed CPAN module installation guide.