=pod

=encoding UTF-8

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

=cut
=pod

=encoding UTF-8

=head1 NAME

Oficially, the software name is C<perl-Dist-Zilla-Plugin-Manifest-Write>.

However, in Perl world prefix "perl-" is redundant and not used. For example, on
L<meta::cpan|https://metacpan.org/> this software is named as C<Dist-Zilla-Plugin-Manifest-Write>. In the rest of the
documentation shortened name C<Dist-Zilla-Plugin-Manifest-Write> is used as synonym for full name C<perl-Dist-Zilla-Plugin-Manifest-Write>.
We are in the Perl world, aren't we?

You may notice that name may be spelled with dashes (C<Dist-Zilla-Plugin-Manifest-Write>) or with double colons (C<Dist::Zilla::Plugin::Manifest::Write>). Strictly speaking, there is difference: the first one is software name, while the
second is name of Perl package, but often these names are interchangeable especially if software
consists of single package.

=cut
=pod

=encoding UTF-8

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

=cut
=pod

=encoding UTF-8

=head1 FORMS

You may face C<Dist-Zilla-Plugin-Manifest-Write> in I<source> or I<distribution> forms.

If you are going to have annotated MANIFEST in your distribution, you will likely be interested in I<using> C<Dist-Zilla-Plugin-Manifest-Write>
I<distribution>. If you are going to I<develop> (or I<hack>) the C<Dist-Zilla-Plugin-Manifest-Write> itself, you will
likely need the I<source>, not distribution.

Since Perl is an interpreting language, modules in the distribution I<look> like sources. Actually,
they are Perl source files. But they are not I<actual> sources, because they are I<built>
(preprocessed or generated) by L<Dist-Zilla>.

How to distinguish source and distribution:

=over

=item *

Source may contain Mercurial files and directories F<.hgignore>, F<.hgtags>, F<.hg/>, while
distribution should not.

=item *

Source should contain files F<dist.ini>, F<weaver.ini>, while distribution may not.

=item *

Source should I<not> contain F<xt/> directory, while distribution should.

=item *

Name of source directory does I<not> include version (e. g. C<Dist-Zilla-Plugin-Manifest-Write>), while name of
distribution does (e. g. C<Dist-Zilla-Plugin-Manifest-Write-0.007>).

=back

=cut
=pod

=encoding UTF-8

=head1 SOURCE

C<Dist-Zilla-Plugin-Manifest-Write> source is in Mercurial repository hosted on L<fedorapeople.org|https://fedorapeople.org>. To  clone the entire repository:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Manifest-Write

=head2 Source files

C<Dist-Zilla-Plugin-Manifest-Write> source files usually include a comment near the top of the file:

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

Not all source files are included into distribution. Some source files are used at distribution
build time only, and not required for installation.

=cut
=pod

=encoding UTF-8

=head1 DISTRIBUTION

C<Dist-Zilla-Plugin-Manifest-Write> distributions are published on L<CPAN|https://metacpan.org/release/Dist-Zilla-Plugin-Manifest-Write>.

=head2 Generated files

Distribution may cointain files preprocessed or generated by C<Dist-Zilla> and its plugins. Some
generated files are made from C<Dist-Zilla-Plugin-Manifest-Write> source, but some are generated from third-party
templates. Files generated from third-party templates usually include a comment near the top of the
file:

    This file was generated with NAME

(where I<NAME> is a name of the plugin generated the file). Such files are I<not> part of C<Dist-Zilla-Plugin-Manifest-Write> source, and C<Dist-Zilla-Plugin-Manifest-Write> copyright and license are not applicable to such files.

=cut
=pod

=encoding UTF-8

=head1 INSTALLING

=head2 With cpanm

C<cpanm> tool is (probably) the easiest way to install distribution. It automates downloading,
building, testing, installing, and uninstalling.

To install the latest version from CPAN:

    $ cpanm Dist::Zilla::Plugin::Manifest::Write

To install a specific version (e. g. I<0.007>) from CPAN:

    $ cpanm Dist::Zilla::Plugin::Manifest::Write@0.007

To install locally available distribution (e. g. previously downloaded from CPAN or built from
sources):

    $ cpanm ./Dist-Zilla-Plugin-Manifest-Write-0.007.tar.gz

To uninstall the distribution:

    $ cpanm -U Dist::Zilla::Plugin::Manifest::Write

=head2 Manually

To install distribution tarball manually (let us assume you have version I<0.007> of the
distribution):

    $ tar xaf Dist-Zilla-Plugin-Manifest-Write-0.007.tar.gz
    $ cd Dist-Zilla-Plugin-Manifest-Write-0.007
    $ perl Build.PL
    $ ./Build build
    $ ./Build test
    $ ./Build install

=head2 See also

L<How to install CPAN modules|http://www.cpan.org/modules/INSTALL.html>

=cut
=pod

=encoding UTF-8

=head1 HACKING

For hacking, you will need Mercurial, Perl interpreter and C<Dist-Zilla> (with some plugins), and
likely C<cpanm> to install missed parts.

Clone the repository first:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Manifest-Write
    $ cd perl-Dist-Zilla-Plugin-Manifest-Write

To build a distribution from the source, run:

    $ dzil build

If required C<Dist-Zilla> plugins are missed, C<dzil> tool will warn you and show the command to
install all the required plugins, e. g.:

    Required plugin Dist::Zilla::Plugin::Test::EOL isn't installed.

    Run 'dzil authordeps' to see a list of all required plugins.
    You can pipe the list to your CPAN client to install or update them:

        dzil authordeps --missing | cpanm

To run the tests:

    $ dzil test

To run all the tests, including release tests:

    $ dzil test --release

To install the distribution:

    $ dzil install

or

    $ cpanm ./Dist-Zilla-Plugin-Manifest-Write-VERSION.tar.gz

where I<VERSION> is a version of built distribution.

To clean the directory:

    $ dzil clean

=cut
=pod

=encoding UTF-8

=head1 DOCUMENTATION

=head2 Online

The easiest way is browsing the documentation L<online at meta::cpan|https://metacpan.org/release/Dist-Zilla-Plugin-Manifest-Write>.

=head2 Locally installed

If you have the distribution installed, use C<perldoc> tool to browse locally
installed documentation:

    $ perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
    $ perldoc Dist::Zilla::Plugin::Manifest::Write

=head2 Built from source

Build C<Dist-Zilla-Plugin-Manifest-Write> first (see L</"HACKING">), then:

    $ PERL5LIB=Dist-Zilla-Plugin-Manifest-Write-VERSION/lib:$PERL5LIB perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
    $ PERL5LIB=Dist-Zilla-Plugin-Manifest-Write-VERSION/lib:$PERL5LIB perldoc Dist::Zilla::Plugin::Manifest::Write

where I<VERSION> is a version of built distribution.

=cut
=pod

=encoding UTF-8

=head1 BUGS

=head2 CPAN request tracker

The quickest way to report a bug in C<Dist-Zilla-Plugin-Manifest-Write> is by sending email to bug-Dist-Zilla-Plugin-Manifest-Write [at]
rt.cpan.org.

CPAN request tracker can be used via web interface also:

=over

=item L<Browse bugs|https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Manifest-Write>

Browsing bugs does not require authentication.

=item L<Report bugs|https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugin-Manifest-Write>

You need to be a CPAN author, have a L<BitCard|https://www.bitcard.org/> account, or OpenID in oder
to report bugs via the web interface.

(On 2015-04-27 I have logged in successfully with my LiveJournal OpenID, but my Google OpenID did
not work for CPAN. I did not check other OpenID providers.)

=back

=head2 Email to author

As a last resort, send email to author: Van de Bugger <van.de.bugger@gmail.com>. Please start message subject with
"Dist-Zilla-Plugin-Manifest-Write:".

=cut
=pod

=encoding UTF-8

=head1 GLOSSARY

=over

=item CPAN

Comprehensive Perl Archive Network, a B<large> collection of Perl software and documentation. See
L<cpan.org|http://www.cpan.org>, L<What is
CPAN?|http://www.cpan.org/misc/cpan-faq.html#What_is_CPAN>.

=item Distribution

Tarball, containing Perl modules and accompanying files (documentation, metainfo, tests). Usually
distributions are uploaded to CPAN, and can be installed with dedicated tools (C<cpan>, C<cpanm>,
and others).

=item Module

Perl library file, usually with C<.pm> suffix. Usually contains one package. See
L<perlmod|http://perldoc.perl.org/perlmod.html#Perl-Modules>.

=item Package

Perl language construct. See L<package|http://perldoc.perl.org/functions/package.html> and
L<perlmod|http://perldoc.perl.org/perlmod.html#Packages>.

=back

=cut
=pod

=encoding UTF-8

=head1 COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

C<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.

C<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
C<perl-Dist-Zilla-Plugin-Manifest-Write>.  If not, see L<http://www.gnu.org/licenses/>.

C<perl-Dist-Zilla-Plugin-Manifest-Write> I<distribution> may contain files generated by
C<Dist-Zilla> and/or its plugins from third-party templates; copyright and license specified above
are I<not> applicable to that files.

=cut
=pod

=encoding UTF-8

=head1 SEE ALSO

=over

=item L<Dist::Zilla> — distribution builder; installer not included!

=item L<Dist::Zilla::Plugin::Manifest> — build a F<MANIFEST> file

=back

=cut

