[Module-build-checkins] Module-Build/lib/Module Build.pm,1.192,1.193

[Randy W. S. <si...@us...>]

Update of /cvsroot/module-build/Module-Build/lib/Module
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv2806/lib/Module

Modified Files:
	Build.pm 
Log Message:
Alter documentation to reflect support for PREFIX-style install paths.

Index: Build.pm
===================================================================
RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build.pm,v
retrieving revision 1.192
retrieving revision 1.193
diff -u -d -r1.192 -r1.193
--- Build.pm	1 Nov 2005 09:58:37 -0000	1.192
+++ Build.pm	3 Nov 2005 01:08:31 -0000	1.193
@@ -343,7 +343,7 @@
 =item install
 
 This action will use C<ExtUtils::Install> to install the files from
-C<blib/> into the system.  See L<How Installation Paths are Determined>
+C<blib/> into the system.  See L<INSTALL PATHS>
 for details about how Module::Build determines where to install
 things, and how to influence this process.
 
@@ -518,10 +518,13 @@
 =back
 
 
-=head2 General Command Line Options
+=head1 OPTIONS
+
+=head2 Command Line Options
 
 The following options can be used during any invocation of Build.PL or
-the Build script, during any action.
+the Build script, during any action. For information on other options
+specific to an action, see the documentation for the respective action.
 
 NOTE: There is some preliminary support for options to use the more
 familiar long option style.  Most options can be preceded with the
@@ -563,7 +566,7 @@
 =back
 
 
-=head2 Default Command Line Options (F<.modulebuildrc>)
+=head2 Default Options File (F<.modulebuildrc>)
 
 When Module::Build starts up, it will look for a file,
 F<$ENV{HOME}/.modulebuildrc>.  If the file exists, the options
@@ -595,7 +598,7 @@
 absolute path of the file containing your options.
 
 
-=head2 How Installation Paths are Determined
+=head1 INSTALL PATHS
 
 When you invoke Module::Build's C<build> action, it needs to figure
 out where to install things.  The nutshell version of how this works
@@ -740,11 +743,10 @@
  libhtml => /home/ken/html
 
 Note that this is I<different> from how MakeMaker's C<PREFIX>
-parameter works.  Module::Build doesn't support MakeMaker's C<PREFIX>
-option.  See L</"Why PREFIX is not supported"> for more details.
-C<install_base> just gives you a default layout under the directory
-you specify, which may have little to do with the C<installdirs=site>
-layout.
+parameter works.  See L</"Why PREFIX is not recommended"> for more
+details.  C<install_base> just gives you a default layout under the
+directory you specify, which may have little to do with the
+C<installdirs=site> layout.
 
 The exact layout under the directory you specify may vary by system -
 we try to do the "sensible" thing on each platform.
@@ -769,41 +771,7 @@
 
 =back
 
-=head1 Alternatives to PREFIX
-
-Module::Build offers L</install_base> as a simple, predictable, and
-user-configurable alternative to ExtUtils::MakeMaker's C<PREFIX>.
-What's more, MakeMaker will soon accept C<INSTALL_BASE> -- we strongly
-urge you to make the switch.
-
-Here's a quick comparison of the two when installing modules to your
-home directory on a unix box:
-
-MakeMaker [*]:
-
-  % perl Makefile.PL PREFIX=/home/spurkis
-  PERL5LIB=/home/spurkis/lib/perl5/5.8.5:/home/spurkis/lib/perl5/site_perl/5.8.5
-  PATH=/home/spurkis/bin
-  MANPATH=/home/spurkis/man
-
-Module::Build:
-
-  % perl Build.PL install_base=/home/spurkis
-  PERL5LIB=/home/spurkis/lib/perl5
-  PATH=/home/spurkis/bin
-  MANPATH=/home/spurkis/man
-
-[*] Note that MakeMaker's behaviour cannot be guaranteed in even this
-common scenario, and differs among different versions of MakeMaker.
-
-In short, using C<install_base> is similar to the following MakeMaker usage:
-
-  perl Makefile.PL PREFIX=/home/spurkis LIB=/home/spurkis/lib/perl5
-
-See L</How Installation Paths are Determined> for details on other
-installation options available and how to configure them.
-
-=head2 Why PREFIX is not supported
+=head2 About PREFIX Support
 
 First, it is necessary to understand the original idea behind
 C<PREFIX>.  If, for example, the default installation locations for
@@ -817,8 +785,10 @@
 
 However, the real world is more complicated than that.  The C<PREFIX>
 idea is fundamentally broken when your machine doesn't jibe with
-C<PREFIX>'s worldview.  A design decision was made not to support it
-in Module::Build, here's a summary of the reasons why:
+C<PREFIX>'s worldview.
+
+
+=head3 Why PREFIX is not recommended
 
 =over 4
 
@@ -867,11 +837,41 @@
 
 =back
 
-=head2 PREFIX will be supported
 
-The current maintainer of MakeMaker has offered to implement C<PREFIX>
-pass-through support in Module::Build B<for backwards compatibility
-only>.  You are still strongly recommended to use C<install_base>.
+=head3 Alternatives to PREFIX
+
+Module::Build offers L</install_base> as a simple, predictable, and
+user-configurable alternative to ExtUtils::MakeMaker's C<PREFIX>.
+What's more, MakeMaker will soon accept C<INSTALL_BASE> -- we strongly
+urge you to make the switch.
+
+Here's a quick comparison of the two when installing modules to your
+home directory on a unix box:
+
+MakeMaker [*]:
+
+  % perl Makefile.PL PREFIX=/home/spurkis
+  PERL5LIB=/home/spurkis/lib/perl5/5.8.5:/home/spurkis/lib/perl5/site_perl/5.8.5
+  PATH=/home/spurkis/bin
+  MANPATH=/home/spurkis/man
+
+Module::Build:
+
+  % perl Build.PL install_base=/home/spurkis
+  PERL5LIB=/home/spurkis/lib/perl5
+  PATH=/home/spurkis/bin
+  MANPATH=/home/spurkis/man
+
+[*] Note that MakeMaker's behaviour cannot be guaranteed in even this
+common scenario, and differs among different versions of MakeMaker.
+
+In short, using C<install_base> is similar to the following MakeMaker usage:
+
+  perl Makefile.PL PREFIX=/home/spurkis LIB=/home/spurkis/lib/perl5
+
+See L</INSTALL PATHS> for details on other
+installation options available and how to configure them.
+
 
 =head1 MOTIVATIONS
 
@@ -950,9 +950,9 @@
 NFS, and it's just generally flimsy.  It would be better to use an MD5
 signature or the like, if available.  See C<cons> for an example.
 
-- append to perllocal.pod
-- write .packlist in appropriate location (needed for un-install)
-- add a 'plugin' functionality
+ - append to perllocal.pod
+ - write .packlist in appropriate location (needed for un-install)
+ - add a 'plugin' functionality
 
 
 =head1 AUTHOR