Various documentation improvements

Changes

@@ -2,6 +2,7 @@ Revision history for ExtUtils-InstallPaths
 
 {{$NEXT}}
           Add original_prefix and install_sets
+          Various documentation improvements
 
 0.005     2012-01-09 23:34:16 Europe/Amsterdam
           Don't return references to internal state

lib/ExtUtils/InstallPaths.pm

@@ -1,4 +1,5 @@
 package ExtUtils::InstallPaths;
+
 use 5.006;
 use strict;
 use warnings;
@@ -222,7 +223,7 @@ sub install_path {
 	return { %{$map} } unless @_;
 
 	my $type = shift;
-	Carp::croak('Type argument missing') unless defined $type ;
+	Carp::croak('Type argument missing') unless defined $type;
 
 	if (@_) {
 		my $new_value = shift;
@@ -532,8 +533,6 @@ sub install_map {
 
 # ABSTRACT: Build.PL install path logic made easy
 
-__END__
-
 =head1 SYNOPSIS
 
  use ExtUtils::InstallPaths;
@@ -546,49 +545,49 @@ __END__
 
 This module tries to make install path resolution as easy as possible.
 
-When you want to install a module, it needs to figure out where to install things. The nutshell version of how this works is that default installation locations are determined from L<ExtUtils::Config>, and they may be overridden by using the C<install_path> attribute. An C<install_base> attribute lets you specify an alternative installation root like F</home/foo> and C<prefix> does something similar in a rather different (and more complicated) way. C<destdir> lets you specify a temporary installation directory like F</tmp/install> in case you want to create bundled-up installable packages.
+When you want to install a module, it needs to figure out where to install things. The nutshell version of how this works is that default installation locations are determined from L<ExtUtils::Config>, and they may be individually overridden by using the C<install_path> attribute. An C<install_base> attribute lets you specify an alternative installation root like F</home/foo> and C<prefix> does something similar in a rather different (and more complicated) way. C<destdir> lets you specify a temporary installation directory like F</tmp/install> in case you want to create bundled-up installable packages.
 
-The following types are supported in any circumstance.
+The following types are supported by default.
 
 =over 4
 
 =item * lib
 
-Usually pure-Perl module files ending in F<.pm>.
+Usually pure-Perl module files ending in F<.pm> or F<.pod>.
 
 =item * arch
 
 "Architecture-dependent" module files, usually produced by compiling XS, L<Inline>, or similar code.
 
 =item * script
 
-Programs written in pure Perl.  In order to improve reuse, try to make these as small as possible - put the code into modules whenever possible.
+Programs written in pure Perl.  In order to improve reuse, you may want to make these as small as possible - put the code into modules whenever possible.
 
 =item * bin
 
 "Architecture-dependent" executable programs, i.e. compiled C code or something.  Pretty rare to see this in a perl distribution, but it happens.
 
 =item * bindoc
 
-Documentation for the stuff in C<script> and C<bin>.  Usually generated from the POD in those files.  Under Unix, these are manual pages belonging to the 'man1' category.
+Documentation for the stuff in C<script> and C<bin>.  Usually generated from the POD in those files.  Under Unix, these are manual pages belonging to the 'man1' category. Unless explicitly set, this is only available on platforms supporting manpages.
 
 =item * libdoc
 
-Documentation for the stuff in C<lib> and C<arch>.  This is usually generated from the POD in F<.pm> files.  Under Unix, these are manual pages belonging to the 'man3' category.
+Documentation for the stuff in C<lib> and C<arch>.  This is usually generated from the POD in F<.pm> and F<.pod> files.  Under Unix, these are manual pages belonging to the 'man3' category. Unless explicitly set, this is only available on platforms supporting manpages.
 
 =item * binhtml
 
-This is the same as C<bindoc> above, but applies to HTML documents.
+This is the same as C<bindoc> above, but applies to HTML documents. Unless explicitly set, this is only available when perl was configured to do so.
 
 =item * libhtml
 
-This is the same as C<bindoc> above, but applies to HTML documents.
+This is the same as C<libdoc> above, but applies to HTML documents. Unless explicitly set, this is only available when perl was configured to do so.
 
 =back
 
 =method new
 
-Create a new ExtUtils::InstallPaths object. B<All attributes are valid arguments> to the contructor, as well as this:
+Create a new ExtUtils::InstallPaths object. B<All attributes are valid arguments> to the constructor, as well as this:
 
 =over 4
 
@@ -620,7 +619,7 @@ Return a map suitable for use with L<ExtUtils::Install>. B<In most cases, this i
 
 =method install_destination($type)
 
-Returns the destination of a certain type
+Returns the destination of a certain type.
 
 =method install_types()
 
@@ -665,7 +664,7 @@ The default destinations for these installable things come from entries in your
 
   lib     => installprivlib  installsitelib      installvendorlib
   arch    => installarchlib  installsitearch     installvendorarch
-  script  => installscript   installsitebin      installvendorbin
+  script  => installscript   installsitescript   installvendorscript
   bin     => installbin      installsitebin      installvendorbin
   bindoc  => installman1dir  installsiteman1dir  installvendorman1dir
   libdoc  => installman3dir  installsiteman3dir  installvendorman3dir
@@ -695,27 +694,27 @@ This sets a prefix, identical to ExtUtils::MakeMaker's PREFIX option. This does
 
 =attr config()
 
-Gets the L<ExtUtils::Config|ExtUtils::Config> object used for this object.
+The L<ExtUtils::Config|ExtUtils::Config> object used for this object.
 
 =attr verbose
 
-Sets the verbosity of ExtUtils::InstallPaths. It defaults to 0
+The verbosity of ExtUtils::InstallPaths. It defaults to 0
 
 =attr blib
 
-Sets the location of the blib directory, it defaults to 'blib'.
+The location of the blib directory, it defaults to 'blib'.
 
 =attr create_packlist
 
-Controls whether a packlist will be added together with C<module_name>. Defaults to 1.
+Together with C<module_name> this controls whether a packlist will be added; it defaults to 1.
 
 =attr dist_name
 
 The name of the current module.
 
 =attr module_name
 
-The name of the main module of the package. This is required for packlist creation, but in the future it may be replaced by dist_name. It defaults to dist_name =~ s/-/::/gr if dist_name is set.
+The name of the main module of the package. This is required for packlist creation, but in the future it may be replaced by dist_name. It defaults to C<dist_name =~ s/-/::/gr> if dist_name is set.
 
 =attr destdir