NAME
    Module::Build::Bundle - subclass for supporting Tasks and Bundles

VERSION
    This documentation describes version 0.01

SYNOPSIS
        #In your Build.PL
        use Module::Build::Bundle;
    
        #Example lifted from: Perl::Critic::logicLAB 
        my $build = Module::Build::Bundle->new(
            dist_author   => 'Jonas B. Nielsen (jonasbn), <jonasbn@cpan.org>',
            module_name   => 'Perl::Critic::logicLAB',
            license       => 'artistic',
            create_readme => 1,
            requires      => {
                'Perl::Critic::Policy::logicLAB::ProhibitUseLib' => '0',
                'Perl::Critic::Policy::logicLAB::RequireVersionFormat' => '0',
            },
        );
    
        $build->create_build_script();

        #In your shell
        % ./Build contents
    
        #Or implicitly executing contents action
        % ./Build
    
DESCRIPTION
  FEATURES
    * Autogeneration of POD for Bundle and Task distributions via a build
    action
    * Links to required/listed distributions, with or without versions
    * Links to specific versions of distributions for perl 5.12.0 if a
    version is specified
    * Inserts a POD section named CONTENTS or something specified by the
    caller

    This module adds a very basic action for propagating a requirements list
    from a Build.PL file's requires section to the a POD section in the
    distribution targetted.

SUBROUTINES/METHODS
  ACTION_contents
    This is the build action parsing the requirements specified in the
    Build.PL file. It creates a POD section (see also FEATURES above).

    By default it overwrites the CONTENTS section with a POD link listing.
    You can specify a note indicating if what section you want to overwrite
    using the section_header note.

        #Example lifted from: Perl::Critic::logicLAB 
        my $build = Module::Build::Bundle->new(
            dist_author   => 'Jonas B. Nielsen (jonasbn), <jonasbn@cpan.org>',
            module_name   => 'Perl::Critic::logicLAB',
            license       => 'artistic',
            create_readme => 1,
            requires      => {
                'Perl::Critic::Policy::logicLAB::ProhibitUseLib' => '0',
                'Perl::Critic::Policy::logicLAB::RequireVersionFormat' => '0',
            },
        );
    
        $build->notes('section_header' => 'POLICIES');

        $build->create_build_script();

    The section of course has to be present.

    Based on your version of perl and you Build.PL requirements, the links
    will be rendered in the following formats:

    Basic:

        #Build.PL
        requires => {
            'Some::Package' => '0',
        }

        #POD, perl all
        =item * L<Some::Package|Some::Package>

    With version:

        #Build.PL
        requires => {
            'Some::Package' => '1.99',
        }

        #POD, perl < 5.12.0
        =item * L<Some::Package|Some::Package>, 1.99

        #POD, perl >= 5.12.0
        =item * L<Some::Package|Some::Package>, L<1\.99\|http://search.cpan.org/dist/Some-Package-1.99/lib/Some/Package.pm>

  ACTION_build
    This is a simple wrapper around the standard action: Module::Build build
    action. It checks whether ACTION_contents have been executed, if not it
    executes it.

  create_mymeta
    This method has been lifted from Module::Build::Base and altered.

    It sets the:

    * 'generated by <package> version <package version>' string in
    MYMETA.yml

    For Module::Build::Bundle:

        #Example MYMETA.yml
        configure_requires:
            Module::Build::Bundle: 0.01
        generated_by: 'Module::Build::Bundle version 0.01'
    
  get_metadata
    This method has been lifted from Module::Build::Base and altered.

    It sets:

    * 'generated by <package> version <package version>' string in META.yml
    * configure_requires: <package>: <version>

    For Module::Build::Bundle:

        #Example META.yml
        configure_requires:
            Module::Build::Bundle: 0.01
        generated_by: 'Module::Build::Bundle version 0.01'

DIAGNOSTICS
    * No <section> section to be replaced
        If the POD to be updated does not contain a placeholder section the
        action will die with the above message.

        The default minimal section should look something like:

            =head1 CONTENTS
    
            =head1
    
        Or if you provide your own section_header

            =head1 <section header>
    
            =head1

CONFIGURATION AND ENVIRONMENT
  CONTENTS SECTION
    The module does per default look for the section named: CONTENTS.

    This is the section used in Bundles, this can be overwritten using the
    section parameter.

    For example Perl::Critic::logicLAB uses a section named POLICIES and
    Task::BeLike::JONASBN uses DEPENDENCIES.

    The problem is that the section has to be present or else the contents
    action will throw an error.

    Module::Build::Bundle is primarily aimed at Bundle distributions. Their
    use is however no longer recommended and Task provides a better way.

DEPENDENCIES
    * perl 5.6.0
    * Module::Build::Base, part of the Module::Build distribution

INCOMPATIBILITIES
    The distribution requires perl version from 5.6.0 and up.

BUGS AND LIMITATIONS
    There are no known bugs or special limitations at this time, but I am
    sure there are plenty of scenarios is distribution packaging the module
    is not currently handling.

    Currently the module only supports Bundle/Task distributions based on
    Module::Build. The implementation is based on a subclass of
    Module::Build, which can replace Module::Build (See: SYNOPSIS).

SEE ALSO
    * Task
    * TaskBeLike::JONASBN
    * Perl::Critic::logicLAB
    * CPAN
    * http://cpansearch.perl.org/src/ANDK/CPAN-1.9402/lib/CPAN/Bundle.pm

MOTIVATION
    The motivation was driven by two things.

    * The joy of fooling around with Module::Build
    * The need for automating the documentation generation

    I have a few perks and one of them is that I never get to automate stuff
    until very late and I always regret that. So when I released
    Bundle::JONASBN, now Task::BeLike::JONASBN::Task::BeLike::JONASBN I
    thought I might aswell get it automated right away.

    This module lived for a long time as a part of Bundle::JONASBN but then
    I needed it for some other distributions, so I decided to separate it
    out.

ACKNOWLEDGEMENTS
    * Adam Kennedy (ADAMK) author of Task, a very basic and simple solution
    * The Module::Build developers

AUTHOR
    * Jonas B. Nielsen (jonasbn) `<jonasbn@cpan.org>'

LICENSE AND COPYRIGHT
    Copyright 2010 jonasbn, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

