Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kentnl/dist-zilla-plugin-readme-brief

Provide a short simple README with just the essentials
https://github.com/kentnl/dist-zilla-plugin-readme-brief

dist-zilla perl

Last synced: about 2 months ago
JSON representation

Provide a short simple README with just the essentials

Awesome Lists containing this project

README 

        
# NAME



Dist::Zilla::Plugin::Readme::Brief - Provide a short simple README with just the essentials



# VERSION



version 0.003003



# SYNOPSIS



    [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



# DESCRIPTION



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



# NOTE



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.



# MECHANICS



- Heading is derived from the `package` statement in the `source_file`

- Description is extracted as the entire `H1Nest` of the section titled `DESCRIPTION` ( or whatever `description_label` is ) in the `source_file`

- Installation instructions are automatically determined by the presence of either

    - A `Makefile.PL` file in your dist ( Where it assumes `EUMM` style )

    - A `Build.PL` file in your dist ( where it assumes `Module::Build` style )

    - In the case of both, only instructions for `Makefile.PL` will be emitted.

    - All of the above behavior can be overridden using the [`installer`](#installer) attribute.

- _ALL_ Copyright and license details are extracted from the `source_file` in any `H1Nest` that has either `COPYRIGHT` or `LICENSE` in the heading.

- Or failing such a section, a `COPYRIGHT AND LICENSE` section will be derived from `zilla->license`



# ATTRIBUTES



## source\_file



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.



This parameter and associated `.pod` support is new in `v0.003000`



## installer



Determines what installers to document in the `INSTALLATION` section.



By default, that section is determined based on the presence of certain

files in your `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`



## description\_label



This case-insensitive attribute defines what `=head1` node will be used for the description section of the brief.



By default, this is `DESCRIPTION`.



This parameter was introduced in version `v0.003000`



# SEE ALSO



Here are some competing modules and how this module differs from them.



- [`[Readme]`](https://metacpan.org/pod/Dist::Zilla::Plugin::Readme)



    Gives a much briefer more generic `README` file, which lacks quite as much readable content,

    and contains no installation instructions.



- [`[ReadmeFromPod]`](https://metacpan.org/pod/Dist::Zilla::Plugin::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 )



- [`[ReadmeAnyFromPod]`](https://metacpan.org/pod/Dist::Zilla::Plugin::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]`](https://metacpan.org/pod/Dist::Zilla::Plugin::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]`](https://metacpan.org/pod/Dist::Zilla::Plugin::InstallGuide)



    The polar opposite approach that only focuses on elaborate installation instructions in `INSTALL`,

    but lacks any of the `POD` and `COPYRIGHT` elements.



# AUTHOR



Kent Fredric 



# COPYRIGHT AND LICENSE



This software is copyright (c) 2020 by Kent Fredric .



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.