#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
#   file: lib/Dist/Zilla/Plugin/Manifes/Write/Manual.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

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

#pod =for :this This is C<Manifest::Write> plugin user manual. Read this if you want to
#pod have annotated MANIFEST in your distribution.
#pod
#pod =for :those If you are going to hack or extend C<Manifest::Write>, read the L<module
#pod documentation|Dist::Zilla::Plugin::Manifest::Write>. General topics like getting source, building, installing, bug
#pod reporting and some others are covered in the F<README>.
#pod
#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod     …
#pod     [GatherDir]         ; Plugin which adds source files to distribution.
#pod                         ; You may use other plugins, like GatherFromManifest.
#pod     [Manifest::Write]
#pod         source_providers = GatherDir
#pod     …
#pod
#pod =head1 DESCRIPTION
#pod
#pod C<Manifest::Write> is a replacement for standard plugin C<Manifest>. To use C<Manifest::Write>, you
#pod 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 source providers, see C<source_providers>
#pod option below.
#pod
#pod =option manifest
#pod
#pod Name of manifest file to write. Default value is F<MANIFEST>. It is unlikely you will need to
#pod change the default value.
#pod
#pod It could be used, though, to generate standard and annotated manifest, e. g.:
#pod
#pod     [Manifest]          ; Writes 'MANIFEST'.
#pod     [Manifest::Write]   ; Writes 'Manifest.new'.
#pod         manifest = Manifest.new
#pod
#pod =option source_providers
#pod
#pod Names of plugins which add I<source files> to distribution. Option may be specified several
#pod times, each value may include several space-separated plugin names, e. g.:
#pod
#pod     source_providers = GatherDir GatherDir::Template
#pod     source_providers = GenerateFile
#pod
#pod There are no default source file providers.
#pod
#pod Note: I<source files> term does B<not> mean exactly Perl sources. Source files are I<your> files,
#pod in contrast to ("3rd party") files added to the distribution by various C<Dist::Zilla> plugins.
#pod Sources may include Perl modules, scripts, POD files, tests, and any other files composing your
#pod 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 =option metainfo_providers
#pod
#pod Names of plugins which add I<meta information files> to the distribution. Option may be specified
#pod several times, each value may include several space-separated plugin names, e. g.:
#pod
#pod     metainfo_providers = MetaYAML MetaJSON Manifest
#pod     metainfo_providers = Manifest::Write
#pod
#pod Default meta info providers are C<MetaYAML>, C<MetaJSON>, C<Manifest>, and C<Manifest::Write>
#pod itself. It seems these metainfo providers should satisfy most of the users (if any).
#pod
#pod Note: Specifying any metainfo provider (even empty one) cancels all the default metainfo providers:
#pod
#pod     [Manifest::Write]
#pod         metainfo_providers =
#pod
#pod =option strict
#pod
#pod Let us consider an example:
#pod
#pod     [Manifest::Write]
#pod         metainfo_providers = MetaYML
#pod
#pod At the first glance it may look ok, but there is a mistake: correct plugin name is C<MetaYAML>, not
#pod C<MetaYML>. Left unnoticed, such a typo may cause bad manifest: files may be classified
#pod incorrectly.
#pod
#pod To avoid such mistakes C<Manifest::Write> checks plugin names specified in C<source_providers> and
#pod C<metainfo_providers> options. Any name specified in these options must be a name of C<Dist::Zilla>
#pod plugin consumed C<FileInjector> role (or C<FileGatherer>, which is a kind of C<FileInjector>). If
#pod not, C<Manifest::Write> will issue error message and abort build process.
#pod
#pod This behaviour may be modified by C<strict> option, which sets the level of strictness. Level 1
#pod behaviour is described above (strict checks, any mistake is fatal), this is default. At level -1
#pod C<Manifest::Write> does not check provider names at all. At level 0 some mistakes are fatal, some
#pod are not. Using a plugin which is not a C<FileInjector> is fatal error. Using a string which is not
#pod a (loaded) plugin name is not fatal (because it I<may be> a name of C<FileInjector> plugin which is
#pod not loaded, e. g. commented out):
#pod
#pod     ; [MetaYAML]
#pod     [Manifest::Write]
#pod         metainfo_providers = MetaYAML
#pod         ;   MetaYAML is a correct name of not loaded plugin,
#pod         ;   but Manifest::Write cannot verify it easily.
#pod         strict = 0
#pod         ;   Print a message but do not abort build.
#pod
#pod =head1 SEE ALSO
#pod
#pod =for :list
#pod = L<Dist::Zilla>
#pod = L<Dist::Zilla::Plugin::Manifest>
#pod = L<Dist::Zilla::Role::FileInjector>
#pod = L<Dist::Zilla::Role::FileGatherer>
#pod = L<Dist::Zilla::Plugin::Manifest::Write>
#pod
#pod =cut

# doc/what.pod #

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

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

#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod F<MANIFEST> is a metainfo file, a part of every distribution. It is a plain list of files included
#pod into the distribution. Typical F<MANIFEST> looks like:
#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 Format of manifest allows comments, but comments are rarely used.
#pod
#pod As it noted before, manifest is a plain list of files. However, files included into a distribution
#pod differ:
#pod
#pod =over
#pod
#pod =item 1.
#pod
#pod Some files are created by software author (in the example above, F<lib/Assa.pm> I<could> be such
#pod file). Some of these files may be processed by various filters (like C<PodWeaver>).
#pod
#pod =item 2.
#pod
#pod Some files contain distribution metainformation (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 Sometimes you may want (or have) to trace an origin of a file: whether this file created by author
#pod or automatically added, if the file was processed or added as-is. With a typical manifest you have
#pod to I<guess> origin of each file, because distribution build tool, C<Dist-Zilla>, throws this
#pod information away. C<Manifest::Write> saves this information in comments:
#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 built by Manifest::Write
#pod     META.yml            #  metainfo file built by MetaYAML
#pod     README              #       Foo file added by GatherFromManifest
#pod     lib/Foo.pm          #       Foo file added by GatherFromManifest and modified by PkgVersion
#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 the example above "Foo" is name of manifested distribution.)
#pod
#pod With such annotated manifest there is no need to I<guess>, you just I<know>.
#pod
#pod =cut

# end of file #


# 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 v0.8.1, released on 2015-09-15 21:00 UTC.

=head1 WHAT?

C<Manifest::Write> is a plugin for C<Dist::Zilla>, a replacement for standard plugin C<Manifest>.
C<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<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 F<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<Manifest::Write> is a replacement for standard plugin C<Manifest>. To use C<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.

It could be used, though, to generate standard and annotated manifest, e. g.:

    [Manifest]          ; Writes 'MANIFEST'.
    [Manifest::Write]   ; Writes 'Manifest.new'.
        manifest = Manifest.new

=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 contrast 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>
itself. 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:

    [Manifest::Write]
        metainfo_providers =

=head2 strict

Let us consider an example:

    [Manifest::Write]
        metainfo_providers = MetaYML

At the first glance it may look ok, but there is a mistake: correct plugin name is C<MetaYAML>, not
C<MetaYML>. Left unnoticed, such a typo may cause bad manifest: files may be classified
incorrectly.

To avoid such mistakes C<Manifest::Write> checks plugin names specified in C<source_providers> and
C<metainfo_providers> options. Any name specified in these options must be a name of C<Dist::Zilla>
plugin consumed C<FileInjector> role (or C<FileGatherer>, which is a kind of C<FileInjector>). If
not, C<Manifest::Write> will issue error message and abort build process.

This behaviour may be modified by C<strict> option, which sets the level of strictness. Level 1
behaviour is described above (strict checks, any mistake is fatal), this is default. At level -1
C<Manifest::Write> does not check provider names at all. At level 0 some mistakes are fatal, some
are not. Using a plugin which is not a C<FileInjector> is fatal error. Using a string which is not
a (loaded) plugin name is not fatal (because it I<may be> a name of C<FileInjector> plugin which is
not loaded, e. g. commented out):

    ; [MetaYAML]
    [Manifest::Write]
        metainfo_providers = MetaYAML
        ;   MetaYAML is a correct name of not loaded plugin,
        ;   but Manifest::Write cannot verify it easily.
        strict = 0
        ;   Print a message but do not abort build.

=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<Manifest::Write> saves this information in comments:

    Build.PL            # 3rd party file added by ModuleBuildTiny
    COPYING             #       Foo file added by GatherFromManifest
    Changes             #       Foo file added by GatherFromManifest
    MANIFEST            #  metainfo file built by Manifest::Write
    META.yml            #  metainfo file built 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::Role::FileInjector>

=item L<Dist::Zilla::Role::FileGatherer>

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

=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
