/ 
Dist-Zilla-Plugin-Manifest-Write-0.002
/ Dist::Zilla::Plugin::Manifest::Write::Manual

NAME

Dist::Zilla::Plugin::Manifest::Write::Manual - Use Manifest::Write Dist::Zilla plugin in your dist.ini

VERSION

Version 0.002.

WHAT?

perl-Dist-Zilla-Plugin-Manifest-Write is a plugin for Dist-Zilla, a replacement for standard plugin Manifest. perl-Dist-Zilla-Plugin-Manifest-Write writes annotated MANIFEST: each file followed by a comment, explaining origin of the file, whether it is part of software, meta information, or 3rd party file.

perl-Dist-Zilla-Plugin-Manifest-Write is free software.

WHY?

Typical MANIFEST file included into a Perl distribution is plain list of all distribution files, a filename per line, e. g.:

Build.PL
COPYING
Changes
MANIFEST
META.yml
README
lib/Foo.pm
t/00-compile.t
xt/author/eol.t
xt/author/no-tabs.t

However, files have different origin:

  1. Some files created by software author (in the example above, lib/Assa.pm could be such file).

  2. Some files contain distribution meta information (META.yml and MANIFEST itself).

  3. Some files may be generated by a tool from third party templates (Dist-Zilla and its plugins can generate a lot of various files, in the example above all the tests could be generated, as well as Build.PL, COPYING, and even Changes).

File origin may be important. For example, if you want to copy a file from a distribution, you have to check the terms of the license first. However, the distribution license covers only files from category #1. Obviuosly, distribution license is not applicable to files from category #3. So, you have to guess whether a file is from category #1 or #3. I do not like guessing. To me it would be much better if MANIFEST clearly states origin of each file (Foo is name of manifested software):

Build.PL            # 3rd party file added by ModuleBuildTiny
COPYING             #       Foo file added by GatherFromManifest
Changes             #       Foo file added by GatherFromManifest
MANIFEST            #  metainfo file generated by Manifest::Write
META.yml            #  metainfo file generated by MetaYAML
README              #       Foo file added by GatherFromManifest
lib/Foo.pm          #       Foo file added by GatherFromManifest and modified by OurPkgVersion
t/00-compile.t      # 3rd party file added by Test::Compile
xt/author/eol.t     # 3rd party file added by Test::EOL
xt/author/no-tabs.t # 3rd party file added by Test::NoTabs

In such a case you know which files are covered by COPYING.

Dist-Zilla-Plugin-Manifest-Write creates such annotated manifests.

SYNOPSIS

In your dist.ini:

[GatherDir]         ; Plugin which adds source files to distribution.
                    ; You may use other plugins, like GatherFromManifest.
[Manifest::Write]
    source_provider = GatherDir

DESCRIPTION

Dist-Zilla-Plugin-Manifest-Write is a Dist::Zilla plugin, a replacement for Manifest standard plugin. To use Dist-Zilla-Plugin-Manifest-Write, you should replace line

[Manifest]

with

[Manifest::Write]

in your dist.ini file, and specify one or more source providers, see source_provider parameter below.

PARAMETERS

manifest

Name of manifest file to write. Default value is MANIFEST. It is unlikely you will need use this parameter.

source_provider

Name of plugin which adds source files to distribution. Parameter may occur several times to specify several plugins. There are no default source file providers.

Note: source files does not mean Perl sources. Source files are your files, including Perl modules, scripts, POD files, and any other files belonging to your software.

You will likely want to specify GatherDir, GatherFromManifest and similar plugins, like GatherDir::Template or GenerateFile.

metainfo_provider

Name of plugin which adds meta information files to distribution. Parameter may occur several times to specify several plugins. Default meta info providers are MetaYAML, MetaJSON, Manifest, and Manifest::Write.

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.

perl-Dist-Zilla-Plugin-Manifest-Write is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Plugin-Manifest-Write is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Plugin-Manifest-Write. If not, see <http://www.gnu.org/licenses/>.