# Dist/Zilla/Plugin/Manifes/Write/Manual.pod #

#pod =pod
#pod
#pod =encoding UTF-8
#pod
#pod =head1 COPYRIGHT AND LICENSE
#pod
#pod Copyright © 2015 Van de Bugger
#pod
#pod This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.
#pod
#pod perl-Dist-Zilla-Plugin-Manifest-Write is free software: you can redistribute it and/or modify
#pod it under the terms of the GNU General Public License as published by the Free Software
#pod Foundation, either version 3 of the License, or (at your option) any later version.
#pod
#pod perl-Dist-Zilla-Plugin-Manifest-Write is distributed in the hope that it will be useful, but
#pod WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
#pod PARTICULAR PURPOSE. See the GNU General Public License for more details.
#pod
#pod You should have received a copy of the GNU General Public License along with
#pod perl-Dist-Zilla-Plugin-Manifest-Write. If not, see <http://www.gnu.org/licenses/>.
#pod
#pod =cut

0

# PODNAME: Dist::Zilla::Plugin::Manifest::Write::Manual
# ABSTRACT: Use C<Manifest::Write> C<Dist::Zilla> plugin in your F<dist.ini>

#pod =pod
#pod
#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<perl-Dist-Zilla-Plugin-Manifest-Write> is a plugin for C<Dist-Zilla>, a replacement for standard plugin C<Manifest>.
#pod C<perl-Dist-Zilla-Plugin-Manifest-Write> writes annotated F<MANIFEST>: each file followed by a comment, explaining
#pod origin of the file, whether it is part of software, meta information, or 3rd party file.
#pod
#pod C<perl-Dist-Zilla-Plugin-Manifest-Write> is free software.
#pod
#pod =cut


#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod     [GatherDir]         ; Plugin which adds source files to distribution.
#pod                         ; You may use other plugins, like GatherFromManifest.
#pod     [Manifest::Write]
#pod         source_provider = GatherDir
#pod
#pod =pod
#pod
#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod Typical F<MANIFEST> file included into a Perl distribution is plain list of all distribution files,
#pod a filename per line, e. g.:
#pod
#pod     Build.PL
#pod     COPYING
#pod     Changes
#pod     MANIFEST
#pod     META.yml
#pod     README
#pod     lib/Foo.pm
#pod     t/00-compile.t
#pod     xt/author/eol.t
#pod     xt/author/no-tabs.t
#pod
#pod However, files have different origin:
#pod
#pod =over
#pod
#pod =item 1.
#pod
#pod Some files created by software author (in the example above, F<lib/Assa.pm> I<could> be such file).
#pod
#pod =item 2.
#pod
#pod Some files contain distribution meta information (F<META.yml> and F<MANIFEST> itself).
#pod
#pod =item 3.
#pod
#pod Some files may be generated by a tool from third party templates (C<Dist-Zilla> and its plugins can
#pod generate a lot of various files, in the example above all the tests I<could> be generated, as well
#pod as F<Build.PL>, F<COPYING>, and even F<Changes>).
#pod
#pod =back
#pod
#pod File origin may be important. For example, if you want to copy a file from a distribution, you have
#pod to check the terms of the license first. However, the distribution license covers only files from
#pod category #1. Obviuosly, distribution license is not applicable to files from category #3. So, you
#pod have to I<guess> whether a file is from category #1 or #3. I do not like guessing. To me it would
#pod be much better if F<MANIFEST> clearly states origin of each file (C<Foo> is name of manifested
#pod software):
#pod
#pod     Build.PL            # 3rd party file added by ModuleBuildTiny
#pod     COPYING             #       Foo file added by GatherFromManifest
#pod     Changes             #       Foo file added by GatherFromManifest
#pod     MANIFEST            #  metainfo file generated by Manifest::Write
#pod     META.yml            #  metainfo file generated by MetaYAML
#pod     README              #       Foo file added by GatherFromManifest
#pod     lib/Foo.pm          #       Foo file added by GatherFromManifest and modified by OurPkgVersion
#pod     t/00-compile.t      # 3rd party file added by Test::Compile
#pod     xt/author/eol.t     # 3rd party file added by Test::EOL
#pod     xt/author/no-tabs.t # 3rd party file added by Test::NoTabs
#pod
#pod In such a case you I<know> which files are covered by F<COPYING>.
#pod
#pod C<Dist-Zilla-Plugin-Manifest-Write> creates such annotated manifests.
#pod
#pod =cut


#pod =head1 DESCRIPTION
#pod
#pod C<Dist-Zilla-Plugin-Manifest-Write> is a C<Dist::Zilla> plugin, a replacement for C<Manifest> standard plugin. To use
#pod C<Dist-Zilla-Plugin-Manifest-Write>, you should replace line
#pod
#pod     [Manifest]
#pod
#pod with
#pod
#pod     [Manifest::Write]
#pod
#pod in your F<dist.ini> file, and specify one or more I<source providers>, see C<source_provider>
#pod parameter below.
#pod
#pod =param manifest
#pod
#pod Name of manifest file to write. Default value is F<MANIFEST>. It is unlikely you will need use this
#pod parameter.
#pod
#pod =param source_provider
#pod
#pod Name of plugin which adds I<source files> to distribution. Parameter may occur several times to
#pod specify several plugins. There are no default source file providers.
#pod
#pod Note: I<source files> does B<not> mean I<Perl sources>. Source files are I<your> files, including
#pod Perl modules, scripts, POD files, and any other files belonging to your software.
#pod
#pod You will likely want to specify C<GatherDir>, C<GatherFromManifest> and similar plugins, like
#pod C<GatherDir::Template> or C<GenerateFile>.
#pod
#pod =param metainfo_provider
#pod
#pod Name of plugin which adds meta information F<files> to distribution. Parameter may occur several
#pod times to specify several plugins. Default meta info providers are C<MetaYAML>, C<MetaJSON>,
#pod C<Manifest>, and C<Manifest::Write>.
#pod
#pod =cut

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::Manifest::Write::Manual - Use C<Manifest::Write> C<Dist::Zilla> plugin in your F<dist.ini>

=head1 VERSION

Version 0.002.

=head1 WHAT?

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

C<perl-Dist-Zilla-Plugin-Manifest-Write> is free software.

=head1 WHY?

Typical F<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:

=over

=item 1.

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

=item 2.

Some files contain distribution meta information (F<META.yml> and F<MANIFEST> itself).

=item 3.

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

=back

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 I<guess> whether a file is from category #1 or #3. I do not like guessing. To me it would
be much better if F<MANIFEST> clearly states origin of each file (C<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 I<know> which files are covered by F<COPYING>.

C<Dist-Zilla-Plugin-Manifest-Write> creates such annotated manifests.

=head1 SYNOPSIS

In your F<dist.ini>:

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

=head1 DESCRIPTION

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

    [Manifest]

with

    [Manifest::Write]

in your F<dist.ini> file, and specify one or more I<source providers>, see C<source_provider>
parameter below.

=head1 PARAMETERS

=head2 manifest

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

=head2 source_provider

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

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

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

=head2 metainfo_provider

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

=head1 AUTHOR

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

=head1 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/>.

=cut
