# lib/Dist/Zilla/Plugin/MetaResources/Template/Manual.pod #


# doc/what.pod #


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


# end of file #


# PODNAME: Dist::Zilla::Plugin::MetaResources::Template::Manual
# ABSTRACT: C<MetaResources::Template> plugin user manual


# end of file #

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::MetaResources::Template::Manual - C<MetaResources::Template> plugin user manual

=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<Manifest::Write> plugin user manual. Read this if you want to use Perl code in distribution "resource" metadata.

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

=head1 SYNOPSIS

In your F<dist.ini>:

    [MetaResources::Template]
        license             = {{ $dist->license->url }}
        bugtracker.web      = https://rt.cpan.org/Public/Dist/Display.html?Name={{ $dist->name }}
        bugtracker.mailto   = mailto:bug-{{ $dist->name }}@rt.cpan.org
        …

=head1 DESCRIPTION

C<Dist-Zilla-Plugin-MetaResources-Template> is a replacement for C<MetaResources> standard plugin. To use C<Dist-Zilla-Plugin-MetaResources-Template>
you should replace line

    [MetaResources]

with

    [MetaResources::Template]

in your F<dist.ini>. Voilà! Now all the plugin options are treated as templates. It means text
surrounded by double braces (e. g. C<< {{ $dist->name }} >>) is evaluated as Perl code, and
result of evaluation replaces the original text (and surrounding double braces). For example:

    name = Foo
    …
    [MetaResources::Template]
        bugtracker.mailto = mailto:bug-{{ $dist->name }}@rt.cpan.org
        # Option value will be "mailto:bug-Foo@rt.cpan.org".

Within Perl code, two variables are set: C<$dist> and C<$plugin>. C<$dist> variable gives you
access to C<Dist-Zilla> instance and various distribution attributes:

    $dit->name          # string
    $dist->version      # string
    $dist->abstract     # string
    $dist->authors      # arrayref
    …

See L<Dist::Zilla/"ATTRIBUTES"> for full list of attributes.

C<$plugin> variable is mostly useless and provided for conformance with other plugins
(C<GenerateFile>, C<GatherDir::Template>, C<TemplateFiles>, etc). In case of complex code (which is
unlikely to happen) you can use it for logging, though:

    {{ …; $plugin->log( "message" ); …; }}
    {{ …; $plugin->log_fatal( "aborting…" ); …; }}

You need to study C<Dist::Zilla> guts in order to understand what could be done through the plugin
reference.

Actual evaluating and replacement (i. e. template processing) is performed by C<Text::Template>
module, so look for the gory details there.

=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 SEE ALSO

=over 4

=item L<Dist::Zilla> — Distribution builder

=item L<Dist::Zilla::Plugin::MetaResources> — Standard plugin

=item L<Text::Template> — Template engine

=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
