#   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#
#   file: lib/Dist/Zilla/Plugin/Hook/ReadMe.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-Hook.
#pod
#pod perl-Dist-Zilla-Plugin-Hook is free software: you can redistribute it and/or modify it under
#pod the terms of the GNU General Public License as published by the Free Software Foundation,
#pod either version 3 of the License, or (at your option) any later version.
#pod
#pod perl-Dist-Zilla-Plugin-Hook is distributed in the hope that it will be useful, but WITHOUT ANY
#pod WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
#pod 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-Hook. If not, see <http://www.gnu.org/licenses/>.
#pod
#pod =cut

# PODNAME: Dist::Zilla::Plugin::Hook::ReadMe
# ABSTRACT: C<Dist::Zilla::Plugin::Hook> ReadMe

#pod =for :this This is C<Dist-Zilla-Plugin-Hook> readme. It covers general topics like getting source, building,
#pod installing, bug reporting and some others.
#pod
#pod =for :that If you want to write C<Dist::Zilla> plugin directly in F<dist.ini>, read the L<manual|Dist::Zilla::Plugin::Hook::Manual>. If you
#pod are going to hack or extend C<Dist-Zilla-Plugin-Hook>, read the L<module documentation|Dist::Zilla::Plugin::Hook>.
#pod
#pod =head1 SEE ALSO
#pod
#pod =for :list
#pod = L<Dist::Zilla>
#pod
#pod =cut

# doc/what.pod #

#pod =encoding UTF-8
#pod
#pod =head1 WHAT?
#pod
#pod C<Dist-Zilla-Plugin-Hook> (or just C<Hook>) is a set of C<Dist-Zilla> plugins. Every plugin executes Perl
#pod code inlined into F<dist.ini> at particular stage of build process.
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 WHY?
#pod
#pod There is C<Dist::Zilla::Plugin::Run> on CPAN, which allows to run Perl code from within
#pod F<dist.ini>, why I wrote one more? Let us consider two examples.
#pod
#pod The first one executes external commands:
#pod
#pod     $cat dist.ini
#pod     name     = RunShell
#pod     abstract = RunShell demo
#pod     version  = 0.001_001
#pod     [Run::BeforeBuild]
#pod         run            = echo "1. begin"
#pod         run_if_release = echo "2. release"
#pod         run_no_release = echo "3. not release"
#pod         run_if_trial   = echo "4. trial"
#pod         run_no_trial   = echo "5. not trial"
#pod         run            = echo "6. end"
#pod     [GenerateFile/Assa.pm]
#pod         filename = lib/Assa.pm
#pod         content  = package Assa; 1;
#pod     [FakeRelease]
#pod
#pod     $ dzil build
#pod     [Run::BeforeBuild] executing: echo "1. begin"
#pod     [Run::BeforeBuild] 1. begin
#pod     [Run::BeforeBuild] executing: echo "6. end"
#pod     [Run::BeforeBuild] 6. end
#pod     [Run::BeforeBuild] executing: echo "5. not trial"
#pod     [Run::BeforeBuild] 5. not trial
#pod     [Run::BeforeBuild] executing: echo "3. not release"
#pod     [Run::BeforeBuild] 3. not release
#pod     [DZ] beginning to build RunShell
#pod     [DZ] writing RunShell in RunShell-0.001_001
#pod     [DZ] building archive with Archive::Tar::Wrapper
#pod     [DZ] writing archive to RunShell-0.001_001-TRIAL.tar.gz
#pod     [DZ] built in RunShell-0.001_001
#pod
#pod
#pod Execution order is err… non-linear. Of course there is an explanation why command were executed in
#pod this particular order, but looking at F<dist.ini> it is not obvious. (It is also unclear why C<Run>
#pod consider the build is I<not> trial, but it may be just a bug.)
#pod
#pod Another example executes Perl code:
#pod
#pod     $cat dist.ini
#pod     name     = RunPerl
#pod     abstract = RunPerl demo
#pod     version  = 0.001_001
#pod     [Run::BeforeBuild]
#pod         eval = my $self = shift( @_ );
#pod         eval = my $dist = $self->zilla;
#pod         eval = $self->log( [ '%s v%s', $dist->name, $dist->version ] );
#pod     [GenerateFile/Assa.pm]
#pod         filename = lib/Assa.pm
#pod         content  = package Assa; 1;
#pod     [FakeRelease]
#pod
#pod     $ dzil build
#pod     [Run::BeforeBuild] evaluating: my $self = shift( @_ );
#pod     [Run::BeforeBuild] my $dist = $self->zilla;
#pod     [Run::BeforeBuild] $self->log( [ '0.001_001 v', $dist->name, $dist->version ] );
#pod     [Run::BeforeBuild] 0.001_001 v
#pod     [DZ] beginning to build RunPerl
#pod     [DZ] writing RunPerl in RunPerl-0.001_001
#pod     [DZ] building archive with Archive::Tar::Wrapper
#pod     [DZ] writing archive to RunPerl-0.001_001-TRIAL.tar.gz
#pod     [DZ] built in RunPerl-0.001_001
#pod
#pod
#pod Look at the last message from C<Run::BeforeBuild> plugin. Surprising? Where is the distribution
#pod name? Why is the character "v" printed after version number? Ah! C<%s> is a special conversion
#pod specifier which was replaced with "something retained for backward compatibility". There is a bunch
#pod of other conversion specifiers: C<%a>, C<%d>, C<%n>,C<%p>, C<%t>, C<%v>, C<%x>,… That effectively
#pod means I cannot use printf-like functions and hashes, because every percent will be replaced with
#pod something or cause error "unknown conversion".
#pod
#pod There is (undocumented) method to avoid it — every percent sign should be doubled:
#pod
#pod     my %%args;
#pod
#pod However, this is err… not quite Perl.
#pod
#pod Let me cite "Philosophy" section of the great C<Text::Template> module:
#pod
#pod     When people make a template module like this one, they almost always
#pod     start by inventing a special syntax for substitutions. For example,
#pod     they build it so that a string like %%VAR%% is replaced with the
#pod     value of $VAR. Then they realize the need extra formatting, so they
#pod     put in some special syntax for formatting. Then they need a loop, so
#pod     they invent a loop syntax. Pretty soon they have a new little
#pod     template language.
#pod
#pod     This approach has two problems: First, their little language is
#pod     crippled. If you need to do something the author hasn't thought of,
#pod     you lose. Second: Who wants to learn another language? You already
#pod     know Perl, so why not use it?
#pod
#pod Look: C<Run> plugin introduced a bunch of F<dist.ini> options: C<run_if_trial>, C<run_no_trial>
#pod (BTW, why not C<run_if_not_trial>?), C<run_if_release>, C<run_no_release>, C<eval>,
#pod C<censor_commands>, C<fatal_errors>, C<quiet>; a bunch of "conversion specifiers": C<%a>, C<%d>,
#pod C<%n>, C<%p>, C<%v>, C<%t>, C<%x>, C<%s>; and bunch of poorly documented rules. It's "a little
#pod crippled language", isn't it?
#pod
#pod Compared to C<Run>, C<Hook> is rather minimalistic: It provides only one option, and it executes
#pod only Perl. All other C<Run> features can be easily implemented in Perl, for example:
#pod
#pod Running external commands:
#pod
#pod     . = system( … );
#pod
#pod Making errors in external commands fatal:
#pod
#pod     . = use autodie ':all';
#pod     . = system( … );
#pod
#pod Making errors in Perl code non-fatal:
#pod
#pod     . = use Try::Tiny;
#pod     . = try { … };
#pod
#pod Checking trial status:
#pod
#pod     . = … if $dist->is_trial;
#pod     ; or
#pod     . = if ( $dist->is_trial ) { … };
#pod
#pod Checking release build:
#pod
#pod     . = … if $ENV{ DZIL_RELEASING };
#pod     ; or
#pod     . = if ( $ENV{ DZIL_RELEASING } ) { … };
#pod
#pod The code is a little bit longer than C<Run> counterparts, but it is well-known full-featured Perl.
#pod
#pod What if you need to pass to an external command something the C<Run> authors have not thought of?
#pod For example, abstract or licence name. There are no conversion specifiers for it, so you lose. But
#pod with C<Hook> it is trivial:
#pod
#pod     . = system( …, $dist->abstract, …, $dist->license->name, … );
#pod
#pod BTW, there are two minor (at the first look) C<Hook> features:
#pod
#pod =for :list
#pod 1. C<Hook> passes arguments provided by C<Dist::Zilla> to the code.
#pod 2. C<Hook> passes return value from the code back to C<Dist::Zilla>.
#pod
#pod which bring a new quality: with C<Hook> you can write inline plugins. For example, a plugin which
#pod reads distribution version from an external file:
#pod
#pod     [Hook::VersionProvider]
#pod         . = use Path::Tiny; path('VERSION' )->slurp;
#pod
#pod (Actually, every hook I<is> an inline plugin.) See more in Examples.
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 NAMING
#pod
#pod C<perl-Dist-Zilla-Plugin-Hook> is official software name.
#pod
#pod However, in Perl world prefix "perl-" is redundant and not used. For example, on
#pod L<meta::cpan|https://metacpan.org/> this software is named as C<Dist-Zilla-Plugin-Hook>. In the rest of the
#pod documentation shortened name C<Dist-Zilla-Plugin-Hook> is used as synonym for full name
#pod C<perl-Dist-Zilla-Plugin-Hook>. We are in the Perl world, aren't we?
#pod
#pod You may notice that name may be spelled with dashes (C<Dist-Zilla-Plugin-Hook>) or with double colons
#pod (C<Dist::Zilla::Plugin::Hook>). Strictly speaking, there is difference: the first one is software name,
#pod while the second is name of Perl package, but often these names are interchangeable especially if
#pod software consists of single package.
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 FORMS
#pod
#pod You may face C<Dist-Zilla-Plugin-Hook> in I<source> or I<distribution> forms.
#pod
#pod If you are going to write C<Dist::Zilla> plugin directly in F<dist.ini>, you will likely be interested in I<using> C<Dist-Zilla-Plugin-Hook>
#pod I<distribution>. If you are going to I<develop> (or I<hack>) the C<Dist-Zilla-Plugin-Hook> itself, you will
#pod likely need the I<source>, not distribution.
#pod
#pod Since Perl is an interpreting language, modules in the distribution I<look> like sources. Actually,
#pod they are Perl source files. But they are not I<actual> sources, because they are I<built>
#pod (preprocessed or generated) by L<Dist-Zilla>.
#pod
#pod How to distinguish source and distribution:
#pod
#pod =over
#pod
#pod =item *
#pod
#pod Source may contain Mercurial files and directories F<.hgignore>, F<.hgtags>, F<.hg/>, while
#pod distribution should not.
#pod
#pod =item *
#pod
#pod Source should contain files F<dist.ini>, F<weaver.ini>, while distribution may not.
#pod
#pod =item *
#pod
#pod Source should I<not> contain F<xt/> directory, while distribution should.
#pod
#pod =item *
#pod
#pod Name of source directory does I<not> include version (e. g. C<Dist-Zilla-Plugin-Hook>), while name of
#pod distribution does (e. g. C<Dist-Zilla-Plugin-Hook-0.007>).
#pod
#pod =back
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 SOURCE
#pod
#pod C<Dist-Zilla-Plugin-Hook> source is in Mercurial repository hosted on fedorapeople.org. To  clone the entire
#pod repository:
#pod
#pod     $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Hook
#pod
#pod =head2 Source Files
#pod
#pod C<Dist-Zilla-Plugin-Hook> source files usually include a comment near the top of the file:
#pod
#pod     This file is part of perl-Dist-Zilla-Plugin-Hook.
#pod
#pod Not all source files are included into distribution. Some source files are used at distribution
#pod build time only, and not required for installation.
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 DISTRIBUTION
#pod
#pod C<Dist-Zilla-Plugin-Hook> distributions are published on L<CPAN|https://metacpan.org/release/Dist-Zilla-Plugin-Hook>.
#pod
#pod =head2 Generated Files
#pod
#pod Distribution may contain files preprocessed or generated by C<Dist-Zilla> and its plugins. Some
#pod generated files are made from C<Dist-Zilla-Plugin-Hook> source, but some are generated from third-party
#pod templates. Files generated from third-party templates usually include a comment near the top of the
#pod file:
#pod
#pod     This file was generated with NAME
#pod
#pod (where I<NAME> is a name of the plugin generated the file). Such files are I<not> part of
#pod C<Dist-Zilla-Plugin-Hook> source, and C<Dist-Zilla-Plugin-Hook> copyright and license are not applicable to such
#pod files.
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 INSTALLING
#pod
#pod =head2 With C<cpanm>
#pod
#pod C<cpanm> tool is (probably) the easiest way to install distribution. It automates downloading,
#pod building, testing, installing, and uninstalling.
#pod
#pod To install the latest version from CPAN:
#pod
#pod     $ cpanm Dist::Zilla::Plugin::Hook
#pod
#pod To install a specific version (e. g. I<0.007>) from CPAN:
#pod
#pod     $ cpanm Dist::Zilla::Plugin::Hook@0.007
#pod
#pod To install locally available distribution (e. g. previously downloaded from CPAN or built from
#pod sources):
#pod
#pod     $ cpanm ./Dist-Zilla-Plugin-Hook-0.007.tar.gz
#pod
#pod To uninstall the distribution:
#pod
#pod     $ cpanm -U Dist::Zilla::Plugin::Hook
#pod
#pod =head2 Manually
#pod
#pod To install distribution tarball manually (let us assume you have version I<0.007> of the
#pod distribution):
#pod
#pod     $ tar xaf Dist-Zilla-Plugin-Hook-0.007.tar.gz
#pod     $ cd Dist-Zilla-Plugin-Hook-0.007
#pod     $ perl Build.PL
#pod     $ ./Build build
#pod     $ ./Build test
#pod     $ ./Build install
#pod
#pod =head2 See Also
#pod
#pod L<How to install CPAN modules|http://www.cpan.org/modules/INSTALL.html>
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 HACKING
#pod
#pod For hacking, you will need Mercurial, Perl interpreter and C<Dist-Zilla> (with some plugins), and
#pod likely C<cpanm> to install missed parts.
#pod
#pod Clone the repository first:
#pod
#pod     $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Hook
#pod     $ cd perl-Dist-Zilla-Plugin-Hook
#pod
#pod To build a distribution from the source, run:
#pod
#pod     $ dzil build
#pod
#pod If required C<Dist-Zilla> plugins are missed, C<dzil> tool will warn you and show the command to
#pod install all the required plugins, e. g.:
#pod
#pod     Required plugin Dist::Zilla::Plugin::Test::EOL isn't installed.
#pod
#pod     Run 'dzil authordeps' to see a list of all required plugins.
#pod     You can pipe the list to your CPAN client to install or update them:
#pod
#pod         dzil authordeps --missing | cpanm
#pod
#pod To run the tests:
#pod
#pod     $ dzil test
#pod
#pod To run all the tests, including release tests:
#pod
#pod     $ dzil test --release
#pod
#pod To install the distribution:
#pod
#pod     $ dzil install
#pod
#pod or
#pod
#pod     $ cpanm ./Dist-Zilla-Plugin-Hook-VERSION.tar.gz
#pod
#pod where I<VERSION> is a version of built distribution.
#pod
#pod To clean the directory:
#pod
#pod     $ dzil clean
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 DOCUMENTATION
#pod
#pod =head2 Online
#pod
#pod The easiest way is browsing the documentation L<online at meta::cpan|https://metacpan.org/release/Dist-Zilla-Plugin-Hook>.
#pod
#pod =head2 Locally Installed
#pod
#pod If you have the distribution installed, use C<perldoc> tool to browse locally
#pod installed documentation:
#pod
#pod     $ perldoc Dist::Zilla::Plugin::Hook::ReadMe
#pod     $ perldoc Dist::Zilla::Plugin::Hook::Manual
#pod     $ perldoc Dist::Zilla::Plugin::Hook
#pod
#pod =head2 Built from Source
#pod
#pod Build C<Dist-Zilla-Plugin-Hook> first (see L</"HACKING">), then:
#pod
#pod     $ cd Dist-Zilla-Plugin-Hook-VERSION
#pod     $ perldoc Dist::Zilla::Plugin::Hook::ReadMe
#pod     $ perldoc Dist::Zilla::Plugin::Hook::Manual
#pod     $ perldoc Dist::Zilla::Plugin::Hook
#pod
#pod where I<VERSION> is a version of built distribution.
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 FEEDBACK
#pod
#pod =head2 CPAN Request Tracker
#pod
#pod The quickest way to report a bug in C<Dist-Zilla-Plugin-Hook> is by sending email to bug-Dist-Zilla-Plugin-Hook [at]
#pod rt.cpan.org.
#pod
#pod CPAN request tracker can be used via web interface also:
#pod
#pod =over
#pod
#pod =item L<Browse bugs|https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Hook>
#pod
#pod Browsing bugs does not require authentication.
#pod
#pod =item L<Report bugs|https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugin-Hook>
#pod
#pod You need to be a CPAN author, have a L<BitCard|https://www.bitcard.org/> account, or OpenID in
#pod order to report bugs via the web interface.
#pod
#pod (On 2015-04-27 I have logged in successfully with my LiveJournal OpenID, but my Google OpenID did
#pod not work for CPAN. I did not check other OpenID providers.)
#pod
#pod =back
#pod
#pod =head2 Send Email to Author
#pod
#pod As a last resort, send email to author: Van de Bugger <van.de.bugger@gmail.com>. Please start message subject with
#pod "perl-Dist-Zilla-Plugin-Hook:".
#pod
#pod =cut

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

#pod =encoding UTF-8
#pod
#pod =head1 GLOSSARY
#pod
#pod =over
#pod
#pod =item CPAN
#pod
#pod Comprehensive Perl Archive Network, a B<large> collection of Perl software and documentation. See
#pod L<cpan.org|http://www.cpan.org>, L<What is
#pod CPAN?|http://www.cpan.org/misc/cpan-faq.html#What_is_CPAN>.
#pod
#pod =item Distribution
#pod
#pod Tarball, containing Perl modules and accompanying files (documentation, metainfo, tests). Usually
#pod distributions are uploaded to CPAN, and can be installed with dedicated tools (C<cpan>, C<cpanm>,
#pod and others).
#pod
#pod =item Module
#pod
#pod Perl library file, usually with C<.pm> suffix. Usually contains one package. See
#pod L<perlmod|http://perldoc.perl.org/perlmod.html#Perl-Modules>.
#pod
#pod =item Package
#pod
#pod Perl language construct. See L<package|http://perldoc.perl.org/functions/package.html> and
#pod L<perlmod|http://perldoc.perl.org/perlmod.html#Packages>.
#pod
#pod =back
#pod
#pod =cut

# end of file #


# end of file #

__END__

=pod

=encoding UTF-8

=head1 NAME

Dist::Zilla::Plugin::Hook::ReadMe - C<Dist::Zilla::Plugin::Hook> ReadMe

=head1 VERSION

Version 0.002, released on 2015-07-23 22:08 UTC.

=head1 WHAT?

C<Dist-Zilla-Plugin-Hook> (or just C<Hook>) is a set of C<Dist-Zilla> plugins. Every plugin executes Perl
code inlined into F<dist.ini> at particular stage of build process.

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

If you want to write C<Dist::Zilla> plugin directly in F<dist.ini>, read the L<manual|Dist::Zilla::Plugin::Hook::Manual>. If you
are going to hack or extend C<Dist-Zilla-Plugin-Hook>, read the L<module documentation|Dist::Zilla::Plugin::Hook>.

=head1 WHY?

There is C<Dist::Zilla::Plugin::Run> on CPAN, which allows to run Perl code from within
F<dist.ini>, why I wrote one more? Let us consider two examples.

The first one executes external commands:

    $cat dist.ini
    name     = RunShell
    abstract = RunShell demo
    version  = 0.001_001
    [Run::BeforeBuild]
        run            = echo "1. begin"
        run_if_release = echo "2. release"
        run_no_release = echo "3. not release"
        run_if_trial   = echo "4. trial"
        run_no_trial   = echo "5. not trial"
        run            = echo "6. end"
    [GenerateFile/Assa.pm]
        filename = lib/Assa.pm
        content  = package Assa; 1;
    [FakeRelease]

    $ dzil build
    [Run::BeforeBuild] executing: echo "1. begin"
    [Run::BeforeBuild] 1. begin
    [Run::BeforeBuild] executing: echo "6. end"
    [Run::BeforeBuild] 6. end
    [Run::BeforeBuild] executing: echo "5. not trial"
    [Run::BeforeBuild] 5. not trial
    [Run::BeforeBuild] executing: echo "3. not release"
    [Run::BeforeBuild] 3. not release
    [DZ] beginning to build RunShell
    [DZ] writing RunShell in RunShell-0.001_001
    [DZ] building archive with Archive::Tar::Wrapper
    [DZ] writing archive to RunShell-0.001_001-TRIAL.tar.gz
    [DZ] built in RunShell-0.001_001

Execution order is err… non-linear. Of course there is an explanation why command were executed in
this particular order, but looking at F<dist.ini> it is not obvious. (It is also unclear why C<Run>
consider the build is I<not> trial, but it may be just a bug.)

Another example executes Perl code:

    $cat dist.ini
    name     = RunPerl
    abstract = RunPerl demo
    version  = 0.001_001
    [Run::BeforeBuild]
        eval = my $self = shift( @_ );
        eval = my $dist = $self->zilla;
        eval = $self->log( [ '%s v%s', $dist->name, $dist->version ] );
    [GenerateFile/Assa.pm]
        filename = lib/Assa.pm
        content  = package Assa; 1;
    [FakeRelease]

    $ dzil build
    [Run::BeforeBuild] evaluating: my $self = shift( @_ );
    [Run::BeforeBuild] my $dist = $self->zilla;
    [Run::BeforeBuild] $self->log( [ '0.001_001 v', $dist->name, $dist->version ] );
    [Run::BeforeBuild] 0.001_001 v
    [DZ] beginning to build RunPerl
    [DZ] writing RunPerl in RunPerl-0.001_001
    [DZ] building archive with Archive::Tar::Wrapper
    [DZ] writing archive to RunPerl-0.001_001-TRIAL.tar.gz
    [DZ] built in RunPerl-0.001_001

Look at the last message from C<Run::BeforeBuild> plugin. Surprising? Where is the distribution
name? Why is the character "v" printed after version number? Ah! C<%s> is a special conversion
specifier which was replaced with "something retained for backward compatibility". There is a bunch
of other conversion specifiers: C<%a>, C<%d>, C<%n>,C<%p>, C<%t>, C<%v>, C<%x>,… That effectively
means I cannot use printf-like functions and hashes, because every percent will be replaced with
something or cause error "unknown conversion".

There is (undocumented) method to avoid it — every percent sign should be doubled:

    my %%args;

However, this is err… not quite Perl.

Let me cite "Philosophy" section of the great C<Text::Template> module:

    When people make a template module like this one, they almost always
    start by inventing a special syntax for substitutions. For example,
    they build it so that a string like %%VAR%% is replaced with the
    value of $VAR. Then they realize the need extra formatting, so they
    put in some special syntax for formatting. Then they need a loop, so
    they invent a loop syntax. Pretty soon they have a new little
    template language.

    This approach has two problems: First, their little language is
    crippled. If you need to do something the author hasn't thought of,
    you lose. Second: Who wants to learn another language? You already
    know Perl, so why not use it?

Look: C<Run> plugin introduced a bunch of F<dist.ini> options: C<run_if_trial>, C<run_no_trial>
(BTW, why not C<run_if_not_trial>?), C<run_if_release>, C<run_no_release>, C<eval>,
C<censor_commands>, C<fatal_errors>, C<quiet>; a bunch of "conversion specifiers": C<%a>, C<%d>,
C<%n>, C<%p>, C<%v>, C<%t>, C<%x>, C<%s>; and bunch of poorly documented rules. It's "a little
crippled language", isn't it?

Compared to C<Run>, C<Hook> is rather minimalistic: It provides only one option, and it executes
only Perl. All other C<Run> features can be easily implemented in Perl, for example:

Running external commands:

    . = system( … );

Making errors in external commands fatal:

    . = use autodie ':all';
    . = system( … );

Making errors in Perl code non-fatal:

    . = use Try::Tiny;
    . = try { … };

Checking trial status:

    . = … if $dist->is_trial;
    ; or
    . = if ( $dist->is_trial ) { … };

Checking release build:

    . = … if $ENV{ DZIL_RELEASING };
    ; or
    . = if ( $ENV{ DZIL_RELEASING } ) { … };

The code is a little bit longer than C<Run> counterparts, but it is well-known full-featured Perl.

What if you need to pass to an external command something the C<Run> authors have not thought of?
For example, abstract or licence name. There are no conversion specifiers for it, so you lose. But
with C<Hook> it is trivial:

    . = system( …, $dist->abstract, …, $dist->license->name, … );

BTW, there are two minor (at the first look) C<Hook> features:

=over 4

=item 1

C<Hook> passes arguments provided by C<Dist::Zilla> to the code.

=item 2

C<Hook> passes return value from the code back to C<Dist::Zilla>.

=back

which bring a new quality: with C<Hook> you can write inline plugins. For example, a plugin which
reads distribution version from an external file:

    [Hook::VersionProvider]
        . = use Path::Tiny; path('VERSION' )->slurp;

(Actually, every hook I<is> an inline plugin.) See more in Examples.

=head1 NAMING

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

You may notice that name may be spelled with dashes (C<Dist-Zilla-Plugin-Hook>) or with double colons
(C<Dist::Zilla::Plugin::Hook>). 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-Hook> in I<source> or I<distribution> forms.

If you are going to write C<Dist::Zilla> plugin directly in F<dist.ini>, you will likely be interested in I<using> C<Dist-Zilla-Plugin-Hook>
I<distribution>. If you are going to I<develop> (or I<hack>) the C<Dist-Zilla-Plugin-Hook> 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-Hook>), while name of
distribution does (e. g. C<Dist-Zilla-Plugin-Hook-0.007>).

=back

=head1 SOURCE

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

=head2 Source Files

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

    This file is part of perl-Dist-Zilla-Plugin-Hook.

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-Hook> distributions are published on L<CPAN|https://metacpan.org/release/Dist-Zilla-Plugin-Hook>.

=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-Hook> 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-Hook> source, and C<Dist-Zilla-Plugin-Hook> 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::Hook

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

    $ cpanm Dist::Zilla::Plugin::Hook@0.007

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

    $ cpanm ./Dist-Zilla-Plugin-Hook-0.007.tar.gz

To uninstall the distribution:

    $ cpanm -U Dist::Zilla::Plugin::Hook

=head2 Manually

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

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

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

=head2 Locally Installed

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

    $ perldoc Dist::Zilla::Plugin::Hook::ReadMe
    $ perldoc Dist::Zilla::Plugin::Hook::Manual
    $ perldoc Dist::Zilla::Plugin::Hook

=head2 Built from Source

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

    $ cd Dist-Zilla-Plugin-Hook-VERSION
    $ perldoc Dist::Zilla::Plugin::Hook::ReadMe
    $ perldoc Dist::Zilla::Plugin::Hook::Manual
    $ perldoc Dist::Zilla::Plugin::Hook

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-Hook> is by sending email to bug-Dist-Zilla-Plugin-Hook [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-Hook>

Browsing bugs does not require authentication.

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

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

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

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

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

=cut
