# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
# lib/Dist/Zilla/Plugin/MetaResources/Template/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-MetaResources-Template.
#pod
#pod perl-Dist-Zilla-Plugin-MetaResources-Template is free software: you can redistribute it and/or
#pod modify 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-MetaResources-Template is distributed in the hope that it will be
#pod useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
#pod FITNESS FOR A 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-MetaResources-Template. If not, see <http://www.gnu.org/licenses/>.
#pod
#pod =cut
# doc/what.pod #
#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<Dist-Zilla-Plugin-MetaResources-Template> is a C<Dist::Zilla> plugin, a replacement for standard plugin C<MetaResources>. Both
#pod provide resources for distribution metadata, but this one treats values as text templates.
#pod
#pod =cut
# end of file #
# doc/why.pod #
#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod By using standard C<MetaResources> plugin you can specify resources for your distribution metadata,
#pod e. g.:
#pod
#pod [MetaResources]
#pod homepage = http://example.org/~AUTHOR/NAME
#pod bugtracker.mailto = bug-NAME@rt.cpan.org
#pod repository.url = git://example.org/AUTHOR/NAME.git
#pod repository.web = http://example.org/AUTHOR/NAME
#pod repository.type = git
#pod
#pod Quite simple, but project name (I<NAME>) appears 5 times in 7 lines — it is far too many to my
#pod taste. Repeating the same name multiple times is boring and error-prone, it complicates project
#pod creation and maintenance.
#pod
#pod I know there are plugins like C<GitHib> or C<Bitbucket> which fulfill the resources. However, they
#pod are not applicable if your project lives at another, less popular hosting, like SourceForge,
#pod Savannah, or TuxFamily. There are no dedicated plugins for these hostings, and probably for many
#pod others.
#pod
#pod C<MetaResources::Template> helps to reduce duplication without introducing any hosting-specific
#pod details. C<MetaResources::Template> treats resources as text templates:
#pod
#pod [MetaResources::Template]
#pod homepage = http://example.org/~AUTHOR/{{ $dist->name }}
#pod bugtracker.web = http://rt.cpan.org/NoAuth/Bugs.html?Dist={{ $dist->name }}
#pod bugtracker.mailto = bug-{{ $dist->name }}@rt.cpan.org
#pod repository.url = git://example.org/AUTHOR/{{ $dist->name }}.git
#pod repository.web = http://example.org/AUTHOR/{{ $dist->name }}
#pod repository.type = git
#pod
#pod =cut
# end of file #
# PODNAME: Dist::Zilla::Plugin::MetaResources::Template::Manual
# ABSTRACT: C<MetaResources::Template> plugin user manual
#pod =for :this This is C<Manifest::Write> plugin user manual. Read this if you want to use Perl code in distribution "resource" metadata.
#pod
#pod =for :that 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
#pod others are covered in the L<readme|Dist::Zilla::Plugin::MetaResources::Template::ReadMe>.
#pod
#pod =head1 SYNOPSIS
#pod
#pod In your F<dist.ini>:
#pod
#pod [MetaResources::Template]
#pod license = {{$dist->license->url}}
#pod bugtracker.web = https://rt.example.org/Public/Dist/Display.html?Name={{$dist->name}}
#pod bugtracker.mailto = mailto:bug-{{$dist->name}}@rt.example.org
#pod …
#pod
#pod =head1 DESCRIPTION
#pod
#pod C<Dist-Zilla-Plugin-MetaResources-Template> is a replacement for C<MetaResources> standard plugin. To use C<Dist-Zilla-Plugin-MetaResources-Template> you should
#pod replace line
#pod
#pod [MetaResources]
#pod
#pod with
#pod
#pod [MetaResources::Template]
#pod
#pod in your F<dist.ini>. Voilà! Now all the plugin options are treated as templates. It means text
#pod surrounded by double braces (e. g. C<< {{$dist->name}} >>) is evaluated as Perl code, and
#pod result of evaluation replaces the original text (and surrounding double braces). For example:
#pod
#pod name = Foo
#pod …
#pod [MetaResources::Template]
#pod bugtracker.mailto = mailto:bug-{{$dist->name}}@rt.example.org
#pod # Option value will be "mailto:bug-Foo@rt.example.org".
#pod
#pod Within Perl code, two variables are set: C<$dist> and C<$plugin>. C<$dist> variable gives you
#pod access to C<Dist::Zilla> instance and various distribution attributes:
#pod
#pod $dit->name # string
#pod $dist->version # string
#pod $dist->abstract # string
#pod $dist->authors # arrayref
#pod …
#pod
#pod See L<Dist::Zilla/"ATTRIBUTES"> for full list of attributes.
#pod
#pod C<$plugin> variable is mostly useless and provided for conformance with other plugins
#pod (C<GenerateFile>, C<GatherDir::Template>, C<TemplateFiles>, etc). In case of complex code (which is
#pod unlikely to happen) you can use it for logging, though:
#pod
#pod {{ …; $plugin->log( "message" ); …; }}
#pod {{ …; $plugin->log_fatal( "aborting…" ); …; }}
#pod
#pod You need to study C<Dist::Zilla> guts in order to understand what could be done through the plugin
#pod reference.
#pod
#pod Actual evaluating and replacement (i. e. template processing) is performed by C<Text::Template>
#pod module, so look for the gory details there.
#pod
#pod =head1 SEE ALSO
#pod
#pod =for :list
#pod = L<Dist::Zilla> — Distribution builder
#pod = L<Dist::Zilla::Plugin::MetaResources> — Standard plugin
#pod = L<Text::Template> — Template engine
#pod = L<CPAN::Meta::Spec> — Distribution metainfo specification
#pod = L<CPAN::Meta::Spec/"resources"> — Specification of "resources"
#pod
#pod =head1 EXAMPLES
#pod
#pod ; file: dist.ini
#pod name = Assa
#pod version = 0.007
#pod author = John Doe <john.doe@example.org>
#pod license = GPL_3::or_later
#pod [GenerateFile/Assa]
#pod filename = lib/Assa.pm
#pod content = package Assa;
#pod content = # ABSTRACT: MetaResources::Template example
#pod content = 1;
#pod [MetaResources::Template]
#pod homepage = http://example.org/{{$dist->name}}
#pod license = {{$dist->license->url}}
#pod bugtracker.web = https://rt.example.org/{{$dist->name}}
#pod bugtracker.mailto = mailto:bug-{{$dist->name}}@rt.example.org
#pod x_plugin = Generated with {{$plugin->plugin_name}}
#pod [MetaYAML]
#pod [MetaJSON]
#pod ; end of file ;
#pod
#pod
#pod =cut
# 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.003, released on 2015-07-22 13:18 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.mailto = mailto:bug-{{$dist->name}}@rt.example.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.example.org
# Option value will be "mailto:bug-Foo@rt.example.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 EXAMPLES
; file: dist.ini
name = Assa
version = 0.007
author = John Doe <john.doe@example.org>
license = GPL_3::or_later
[GenerateFile/Assa]
filename = lib/Assa.pm
content = package Assa;
content = # ABSTRACT: MetaResources::Template example
content = 1;
[MetaResources::Template]
homepage = http://example.org/{{$dist->name}}
license = {{$dist->license->url}}
bugtracker.web = https://rt.example.org/{{$dist->name}}
bugtracker.mailto = mailto:bug-{{$dist->name}}@rt.example.org
x_plugin = Generated with {{$plugin->plugin_name}}
[MetaYAML]
[MetaJSON]
; end of file ;
=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.mailto = bug-NAME@rt.cpan.org
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
=item L<CPAN::Meta::Spec> — Distribution metainfo specification
=item L<CPAN::Meta::Spec/"resources"> — Specification of "resources"
=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