=head1 PREREQUISITES
-There are three basic types of prerequisites that can be defined: 1)
-"requires" - are versions of modules that are required for certain
-functionality to be available; 2) "recommends" - are versions of
-modules that are recommended to provide enhanced functionality; and 3)
-"conflicts" - are versions of modules that conflict with, and that can
-cause problems with the distribution.
+=head2 Types of prerequisites
-Each of the three types of prerequisites listed above can be applied
-to different aspects of the Build process. For the module distribution
-itself you simply define "requires", "recommends", or "conflicts". The
-types can also apply to other aspects of the Build process. Currently,
-only "build_requires" is defined which is used for modules which are
-required during the Build process.
+To specify what versions of other modules are used by this
+distribution, several types of prerequisites can be defined with the
+following parameters:
+=over 3
+
+=item configure_requires
+
+Items that must be installed I<before> configuring this distribution
+(i.e. before running the F<Build.PL> script). This might be a
+specific minimum version of C<Module::Build> or any other module the
+F<Build.PL> needs in order to do its stuff. Clients like C<CPAN.pm>
+or C<CPANPLUS> will be expected to pick C<configure_requires> out of the
+F<META.yml> file and install these items before running the
+C<Build.PL>.
+
+*TODO* auto-add M::B? In what circumstances?
+
+=item build_requires
+
+Items that are necessary for building and testing this distribution,
+but aren't necessary after installation. This can help users who only
+want to install these items temporarily. It also helps reduce the
+size of the CPAN dependency graph if everything isn't smooshed into
+C<requires>.
+
+=item requires
+
+Items that are necessary for basic functioning.
+
+=item recommends
+
+Items that are recommended for enhanced functionality, but there are
+ways to use this distribution without having them installed. You
+might also think of this as "can use" or "is aware of" or "changes
+behavior in the presence of".
+
+=item conflicts
+
+Items that can cause problems with this distribution when installed.
+This is pretty rare.
+
+=back
=head2 Format of prerequisites
perl => '5.6.0'
},
-These four version specifiers have different effects. The value
+The above four version specifiers have different effects. The value
C<'2.4'> means that B<at least> version 2.4 of C<Foo::Module> must be
installed. The value C<0> means that B<any> version of C<Bar::Module>
is acceptable, even if C<Bar::Module> doesn't define a version. The
dependency-checking semantics are available, except that we also
understand perl's new double-dotted version numbers.
+=head2 XS Extensions
+
+Modules which need to compile XS code should list C<ExtUtils::CBuilder>
+as a C<build_requires> element.
+
=head1 SAVING CONFIGURATION INFORMATION
part).
These days, C<h2xs> has largely been superseded by modules like
-C<ExtUtils::ModuleMaker>, C<Module::Starter>, and C<Module::Maker>.
-They have varying degrees of support for C<Module::Build>.
+C<ExtUtils::ModuleMaker>, and C<Module::Starter>. They have varying
+degrees of support for C<Module::Build>.
=head1 AUTOMATION