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


# doc/what.pod #


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


# end of file #
# doc/generic/naming.pod #


# end of file #
# doc/generic/forms.pod #


# end of file #
# doc/generic/source.pod #


# end of file #
# doc/generic/distribution.pod #


# end of file #
# doc/generic/installing.pod #


# end of file #
# doc/generic/hacking.pod #


# end of file #
# doc/generic/documentation.pod #


# end of file #
# doc/generic/feedback.pod #


# end of file #
# doc/generic/glossary.pod #


# end of file #


# PODNAME: Dist::Zilla::Plugin::MetaResources::Template::ReadMe
# ABSTRACT: C<Dist::Zilla::Plugin::MetaResources::Template> ReadMe


# end of file #

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::MetaResources::Template::ReadMe - C<Dist::Zilla::Plugin::MetaResources::Template> ReadMe

=head1 VERSION

Version 0.001, released on 2015-07-09 18:08 UTC.

=head1 WHAT?

C<Dist-Zilla-Plugin-MetaResources-Template> is a C<Dist::Zilla> plugin, a replacement for standard plugin C<MetaResources>. Both
provide resources for distribution metadata, but this one treats values as text templates.

This is C<Dist-Zilla-Plugin-MetaResources-Template> readme. It covers general topics like getting source, building,
installing, bug reporting and some others.

If you want to use Perl code in distribution "resource" metadata, read the L<manual|Dist::Zilla::Plugin::MetaResources::Template::Manual>. If you are
going to hack or extend C<Dist-Zilla-Plugin-MetaResources-Template>, read the L<module documentation|Dist::Zilla::Plugin::MetaResources::Template>.

=head1 WHY?

By using standard C<MetaResources> plugin you can specify resources for your distribution metadata,
e. g.:

    [MetaResources]
        homepage          = http://example.org/~AUTHOR/NAME
        bugtracker.web    = http://rt.cpan.org/NoAuth/Bugs.html?Dist=NAME
        bugtracker.mailto = bug-NAME@rt.cpan.org
        repository.url    = git://example.org/AUTHOR/NAME.git
        repository.web    = http://example.org/AUTHOR/NAME
        repository.type   = git

Quite simple, but project name (I<NAME>) appears 5 times in 7 lines — it is far too many to my
taste. Repeating the same name multiple times is boring and error-prone, it complicates project
creation and maintenance.

I know there are plugins like C<GitHib> or C<Bitbucket> which fulfill the resources. However, they
are not applicable if your project lives at another, less popular hosting, like SourceForge,
Savannah, or TuxFamily. There are no dedicated plugins for these hostings, and probably for many
others.

C<MetaResources::Template> helps to reduce duplication without introducing any hosting-specific
details. C<MetaResources::Template> treats resources as text templates:

    [MetaResources::Template]
        homepage          = http://example.org/~AUTHOR/{{ $dist->name }}
        bugtracker.web    = http://rt.cpan.org/NoAuth/Bugs.html?Dist={{ $dist->name }}
        bugtracker.mailto = bug-{{ $dist->name }}@rt.cpan.org
        repository.url    = git://example.org/AUTHOR/{{ $dist->name }}.git
        repository.web    = http://example.org/AUTHOR/{{ $dist->name }}
        repository.type   = git

=head1 NAMING

C<perl-Dist-Zilla-Plugin-MetaResources-Template> is official software name.

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-MetaResources-Template>. In the documentation
shortened name C<Dist-Zilla-Plugin-MetaResources-Template> is used as synonym for full name C<perl-Dist-Zilla-Plugin-MetaResources-Template>. We are in the
Perl world, aren't we?

You may notice that name may be spelled with dashes (C<Dist-Zilla-Plugin-MetaResources-Template>) or with double colons (C<Dist::Zilla::Plugin::MetaResources::Template>). 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.

=head1 FORMS

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

If you are going to use Perl code in distribution "resource" metadata, you will likely be interested in I<using> C<Dist-Zilla-Plugin-MetaResources-Template>
I<distribution>. If you are going to I<develop> (or I<hack>) the C<Dist-Zilla-Plugin-MetaResources-Template> 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-MetaResources-Template>), while name of
distribution does (e. g. C<Dist-Zilla-Plugin-MetaResources-Template-0.007>).

=back

=head1 SOURCE

C<Dist-Zilla-Plugin-MetaResources-Template> 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-MetaResources-Template

=head2 Source Files

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

    This file is part of perl-Dist-Zilla-Plugin-MetaResources-Template.

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

=head1 DISTRIBUTION

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

=head2 Generated Files

Distribution may contain files preprocessed or generated by C<Dist-Zilla> and its plugins. Some
generated files are made from C<Dist-Zilla-Plugin-MetaResources-Template> 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-MetaResources-Template> source, and C<Dist-Zilla-Plugin-MetaResources-Template> copyright and license are not applicable to such files.

=head1 INSTALLING

=head2 With C<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::MetaResources::Template

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

    $ cpanm Dist::Zilla::Plugin::MetaResources::Template@0.007

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

    $ cpanm ./Dist-Zilla-Plugin-MetaResources-Template-0.007.tar.gz

To uninstall the distribution:

    $ cpanm -U Dist::Zilla::Plugin::MetaResources::Template

=head2 Manually

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

    $ tar xaf Dist-Zilla-Plugin-MetaResources-Template-0.007.tar.gz
    $ cd Dist-Zilla-Plugin-MetaResources-Template-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>

=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-MetaResources-Template
    $ cd perl-Dist-Zilla-Plugin-MetaResources-Template

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-MetaResources-Template-VERSION.tar.gz

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

To clean the directory:

    $ dzil clean

=head1 DOCUMENTATION

=head2 Online

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

=head2 Locally Installed

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

    $ perldoc Dist::Zilla::Plugin::MetaResources::Template::ReadMe
    $ perldoc Dist::Zilla::Plugin::MetaResources::Template::Manual
    $ perldoc Dist::Zilla::Plugin::MetaResources::Template

=head2 Built from Source

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

    $ cd Dist-Zilla-Plugin-MetaResources-Template-VERSION
    $ perldoc Dist::Zilla::Plugin::MetaResources::Template::ReadMe
    $ perldoc Dist::Zilla::Plugin::MetaResources::Template::Manual
    $ perldoc Dist::Zilla::Plugin::MetaResources::Template

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

=head1 FEEDBACK

=head2 CPAN Request Tracker

The quickest way to report a bug in C<Dist-Zilla-Plugin-MetaResources-Template> is by sending email to bug-Dist-Zilla-Plugin-MetaResources-Template [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-MetaResources-Template>

Browsing bugs does not require authentication.

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

You need to be a CPAN author, have a L<BitCard|https://www.bitcard.org/> account, or OpenID in
order 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 Send 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-MetaResources-Template:".

=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

=head1 SEE ALSO

=over 4

=item L<Dist::Zilla>

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

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

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

=cut
