Merge branch 'doc-fixes'

This improves the documentation of Module::Build::Compat and
dynamic_config

Author: Leont

lib/Module/Build/API.pod

@@ -356,17 +356,16 @@ L</module_name>.
 [version 0.07]
 
 A boolean flag indicating whether the F<Build.PL> file must be
-executed, or whether this module can be built, tested and installed
+executed to determine prerequisites, or whether they can be determined
 solely from consulting its metadata file.  The main reason to set this
-to a true value is that your module performs some dynamic
-configuration as part of its build/install process.  If the flag is
-omitted, the F<META.yml> spec says that installation tools should
-treat it as 1 (true), because this is a safer way to behave.
+to a true value is that your module adds or removes prerequisites
+dynamically in F<Build.PL>.  If the flag is omitted, it will be treated
+as 1 (true), because this is a safer way to behave.
 
 Currently C<Module::Build> doesn't actually do anything with this flag
 - it's up to higher-level tools like C<CPAN.pm> to do something useful
-with it.  It can potentially bring lots of security, packaging, and
-convenience improvements.
+with it.  It can also be very helpful for static analysis.  See
+L<CPAN::Meta::Spec/dynamic_config> for details on the metadata field.
 
 =item extra_compiler_flags
 

lib/Module/Build/Compat.pm

@@ -477,6 +477,13 @@ F<Makefile.PL> for you, in one of several different styles.
 C<Module::Build::Compat> also provides some code that helps out the
 F<Makefile.PL> at runtime.
 
+=head1 WARNING
+
+Note that C<Module::Build::Compat> more often causes installation issues
+than solves them, and each of the three F<Makefile.PL> generation styles
+has unique compatibility or functionality issues that are unlikely to be
+fixed. Thus, the use of this module and C<create_makefile_pl> is
+discouraged.
 
 =head1 METHODS
 
@@ -506,6 +513,8 @@ You don't want to use this style if during the C<perl Build.PL> stage
 you ask the user questions, or do some auto-sensing about the user's
 environment, or if you subclass C<Module::Build> to do some
 customization, because the vanilla F<Makefile.PL> won't do any of that.
+Many standard C<Module::Build> features such as C<test_requires> are also
+not supported.
 
 =item small
 
@@ -514,6 +523,13 @@ through to the F<Build.PL> script in the same directory.  The user must
 already have C<Module::Build> installed in order to use this, or else
 they'll get a module-not-found error.
 
+This style attempts (with varying success) to translate the F<Makefile.PL>
+protocol to F<Build.PL>, and is unnecessary on any modern toolchain that
+recognizes C<configure_requires> metadata described below, as F<Build.PL>
+will be run by default in this case. See
+L<https://rt.cpan.org/Public/Bug/Display.html?id=75936> for an example of
+the issues it may cause.
+
 =item passthrough (DEPRECATED)
 
 This is just like the C<small> option above, but if C<Module::Build> is