WHAT?

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

WHY?

By using standard 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 (*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 GitHib or 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.

MetaResources::Template helps to reduce duplication without introducing any
hosting-specific details. 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

NAMING

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

However, in Perl world prefix "perl-" is redundant and not used. For example, on
meta::cpan <https://metacpan.org/> this software is named as
Dist-Zilla-Plugin-MetaResources-Template. In the rest of the documentation
shortened name Dist-Zilla-Plugin-MetaResources-Template is used as synonym for
full name 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
(Dist-Zilla-Plugin-MetaResources-Template) or with double colons
(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.

FORMS

You may face Dist-Zilla-Plugin-MetaResources-Template in *source* or
*distribution* forms.

If you are going to use Perl code in distribution "resource" metadata, you will
likely be interested in *using* Dist-Zilla-Plugin-MetaResources-Template
*distribution*. If you are going to *develop* (or *hack*) the
Dist-Zilla-Plugin-MetaResources-Template itself, you will likely need the
*source*, not distribution.

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

How to distinguish source and distribution:

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

*   Source should contain files dist.ini, weaver.ini, while distribution may
    not.

*   Source should *not* contain xt/ directory, while distribution should.

*   Name of source directory does *not* include version (e. g.
    Dist-Zilla-Plugin-MetaResources-Template), while name of distribution does
    (e. g. Dist-Zilla-Plugin-MetaResources-Template-0.007).

SOURCE

Dist-Zilla-Plugin-MetaResources-Template source is in Mercurial repository
hosted on fedorapeople.org. To clone the entire repository:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-MetaResources-Template/ \
        perl-Dist-Zilla-Plugin-MetaResources-Template

Source Files

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.

DISTRIBUTION

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

Generated Files

Distribution may contain files preprocessed or generated by Dist-Zilla and its
plugins. Some generated files are made from
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 *NAME* is a name of the plugin generated the file). Such files are *not*
part of Dist-Zilla-Plugin-MetaResources-Template source, and
Dist-Zilla-Plugin-MetaResources-Template copyright and license are not
applicable to such files.

INSTALLING

With cpanm

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

Manually

To install distribution tarball manually (let us assume you have version *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

See Also

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

HACKING

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

Clone the repository first:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-MetaResources-Template/ \
        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 Dist-Zilla plugins are missed, 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 *VERSION* is a version of built distribution.

To clean the directory:

    $ dzil clean

DOCUMENTATION

Online

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

Locally Installed

If you have the distribution installed, use 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

Built from Source

Build Dist-Zilla-Plugin-MetaResources-Template first (see "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 *VERSION* is a version of built distribution.

FEEDBACK

CPAN Request Tracker

The quickest way to report a bug in 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:

Browse bugs
<https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-MetaResourc
es-Template>
    Browsing bugs does not require authentication.

Report bugs
<https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugin-MetaResource
s-Template>
    You need to be a CPAN author, have a 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.)

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
"perl-Dist-Zilla-Plugin-MetaResources-Template:".

GLOSSARY

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

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

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

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