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


# doc/what.pod #


# end of file #
# doc/why.pod #


# end of file #


# PODNAME: Dist::Zilla::Plugin::Manifest::Write::Manual
# ABSTRACT: C<Manifest::Write> plugin user manual


# end of file #

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::Manifest::Write::Manual - C<Manifest::Write> plugin user manual

=head1 VERSION

Version 0.004, released on 2015-07-09 14:23 UTC.

=head1 WHAT?

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

This is C<Manifest::Write> plugin user manual. Read this if you want to have annotated MANIFEST in your distribution.

If you are going to hack or extend C<Dist-Zilla-Plugin-Manifest-Write>, read the L<module documentation|Dist::Zilla::Plugin::Manifest::Write>. General topics like getting source, building, installing, bug reporting and some
others are covered in the L<C<ReadMe>|Dist::Zilla::Plugin::Manifest::Write::ReadMe>.

=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_providers = GatherDir
    …

=head1 DESCRIPTION

C<Dist-Zilla-Plugin-Manifest-Write> is 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 source providers, see C<source_providers>
option below.

=head1 OPTIONS

=head2 manifest

Name of manifest file to write. Default value is F<MANIFEST>. It is unlikely you will need to
change the default value.

=head2 source_providers

Names of plugins which add I<source files> to distribution. Option may be specified several
times, each value may include several space-separated plugin names, e. g.:

    source_providers = GatherDir GatherDir::Template
    source_providers = GenerateFile

There are no default source file providers.

Note: I<source files> term does B<not> mean exactly Perl sources. Source files are I<your> files,
in contract to ("3rd party") files added to the distribution by various C<Dist::Zilla> plugins.
Sources may include Perl modules, scripts, POD files, tests, and any other files composing your
software.

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

=head2 metainfo_providers

Names of plugins which add I<meta information files> to the distribution. Option may be specified
several times, each value may include several space-separated plugin names, e. g.:

    metainfo_providers = MetaYAML MetaJSON Manifest
    metainfo_providers = Manifest::Write

Default meta info providers are C<MetaYAML>, C<MetaJSON>, C<Manifest>, and C<Manifest::Write>. It
seems these metainfo providers should satisfy most of the users (if any).

Note: Specifying any metainfo provider (even empty one) cancels all the default metainfo providers.

=head1 WHY?

F<MANIFEST> is a metainfo file, a part of every distribution. It is a plain list of files included
into the distribution. Typical F<MANIFEST> looks like:

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

Format of manifest allows comments, but comments are rarely used.

As it noted before, manifest is a plain list of files. However, files included into a distribution
differ:

=over

=item 1.

Some files are created by software author (in the example above, F<lib/Assa.pm> I<could> be such
file). Some of these files may be processed by various filters (like C<PodWeaver>).

=item 2.

Some files contain distribution metainformation (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

Sometimes you may want (or have) to trace an origin of a file: whether this file created by author
or automatically added, if the file was processed or added as-is. With a typical manifest you have
to I<guess> origin of each file, because distribution build tool, C<Dist-Zilla>, throws this
information away. C<Dist-Zilla-Plugin-Manifest-Write> saves this information in comments, e. g.:

    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 PkgVersion
    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 the example above "Foo" is name of manifested distribution.)

With such annotated manifest there is no need to I<guess>, you just I<know>.

=head1 SEE ALSO

=over 4

=item L<Dist::Zilla>

=item L<Dist::Zilla::Plugin::Manifest>

=item L<Dist::Zilla::Plugin::Manifest::Write>

=item L<Dist::Zilla::Plugin::Manifest::Write::ReadMe>

=back

=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
